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} + + + + + Magnum Emscripten Application + + + +

Magnum Emscripten Application

+
+ +
Initialization...
+
+ + +
+ + +@endcode + +Replace @cb{.jinja} {{ application }} @ce with the name of your application +executable. You can modify all the files to your liking, but the HTML file must +contain at least the @cb{.html} @ce enclosed in listener +@cb{.html}
@ce. The JavaScript file contains event listeners which print +loading status on the page. The status displayed in the remaining two +@cb{.html}
@ce s, if they are available. The CSS file contains +a rudimentary style. + +In order to deploy the app, you need to install the JS driver code, the +WebAssembly binary (or the asm.js memory image, in case you are compiling +with the classic asm.js toolchain), the HTML markup and the JS/CSS modules to a +common location. The following CMake snippet handles all of that: + +@code{.cmake} +if(CORRADE_TARGET_EMSCRIPTEN) + install(TARGETS my-application DESTINATION ${CMAKE_INSTALL_PREFIX}) + install(FILES + my-application.html + EmscriptenApplication.js + WebApplication.css + DESTINATION ${CMAKE_INSTALL_PREFIX}) + install(FILES + ${CMAKE_CURRENT_BINARY_DIR}/my-application.js.mem + ${CMAKE_CURRENT_BINARY_DIR}/my-application.wasm + DESTINATION ${CMAKE_INSTALL_PREFIX} OPTIONAL) +endif() +@endcode + +To deploy, you can either point `CMAKE_INSTALL_PREFIX` to a location inside +your system webserver or you can point it to an arbitrary directory and use +Python's builtin webserver to serve its contents: + +@code{.sh} +cd build-emscripten-wasm +cmake -DCMAKE_INSTALL_PREFIX=/path/to/my/emscripten/deploy .. +cmake --build . --target install + +cd /path/to/my/emscripten/deploy +python -m http.server +@endcode + +After that, you can open http://localhost:8000 to see the files. Stop the +webserver again by pressing @m_class{m-label m-warning} **Ctrl** +@m_class{m-label m-default} **C**. + +@section platforms-html5-windowless-apps Building and deploying windowless apps + +In case you don't have an EGL + OpenGL ES build set up yet, you need to copy +`FindEGL.cmake` and `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 +EGL and WebGL libraries. + +Windowless Magnum apps (i.e. apps that use the OpenGL context without a window) +can be run in the browser as well using the @ref Platform::WindowlessEglApplication +class. 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::WindowlessEglApplication also contains a fully + configured bootstrap project that's ready to build and deploy. Check its + documentation for details. + +Similarly to graphics apps, you need to provide a HTML markup for your +application. Template one is below, its main difference from the one above is +that it shows the console output instead of the canvas. The markup references +two files, `WindowlessEmscriptenApplication.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} + + + + + Magnum Windowless Emscripten Application + + + +

Magnum Windowless Emscripten Application

+
+ +

+      
Initialization...
+
+ + +
+ + +@endcode + +Replace @cb{.jinja} {{ application }} @ce with the name of your application +executable. You can modify all the files to your liking, but the HTML file must +contain at least the @cb{.html} @ce enclosed in listener @cb{.html}
@ce +and the @cb{.html}
 @ce for displaying the output. The JavaScript
+file contains event listeners which print loading status on the page. The
+status displayed in the remaining two @cb{.html} 
@ce s, if they are +available. The CSS file contains a rudimentary style. + +Deployment is similar to @ref platforms-html5-apps "graphics apps", only +referencing a different JS file: + +@code{.cmake} +if(CORRADE_TARGET_EMSCRIPTEN) + install(TARGETS my-application DESTINATION ${CMAKE_INSTALL_PREFIX}) + install(FILES + my-application.html + WindowlessEmscriptenApplication.js + WebApplication.css + DESTINATION ${CMAKE_INSTALL_PREFIX}) + install(FILES + ${CMAKE_CURRENT_BINARY_DIR}/my-application.js.mem + ${CMAKE_CURRENT_BINARY_DIR}/my-application.wasm + DESTINATION ${CMAKE_INSTALL_PREFIX} OPTIONAL) +endif() +@endcode + +@section platforms-html5-environment Terminal output, environment and command-line arguments + +When running console apps using Node.js, command-line arguments and terminal +output work like usual. + +For graphics apps in the browser, `EmscriptenApplication.js` redirects all +output (thus also @ref Corrade::Utility::Debug "Debug", +@ref Corrade::Utility::Warning "Warning" and @ref Corrade::Utility::Error "Error") +to JavaScript console. For windowless apps, `WindowlessEmscriptenApplication.js` +redirects output to the @cb{.html}
 @ce element on the page.
+
+It's possible to pass command-line arguments to @cpp main() @ce using GET URL
+parameters. For example, `/app/?foo=bar&fizz&buzz=3` will go to the app as
+@cb{.py} ['--foo', 'bar', '--fizz', '--buzz', '3'] @ce.
+
+Emscripten provides its own set of environment variables through
+@ref std::getenv() and doesn't expose system environment when running through
+Node.js. In order to access system environment, you can use the
+@ref Corrade::Utility::Arguments class, especially
+@ref Corrade::Utility::Arguments::environment().
 
 @section platforms-html5-webgl Differences between WebGL and OpenGL ES
 
diff --git a/src/Magnum/Audio/al-info.cpp b/src/Magnum/Audio/al-info.cpp
index 5fc559a2e..007304a76 100644
--- a/src/Magnum/Audio/al-info.cpp
+++ b/src/Magnum/Audio/al-info.cpp
@@ -55,9 +55,8 @@ Arguments:
 When installing Magnum, point the `MAGNUM_DEPLOY_PREFIX` CMake variable to your
 webserver location. The Magnum Info utility is then available in a `magnum-al-info/`
 subdirectory of given location. You can pass all command-line arguments from
-above to it via GET parameters. See the relevant section of
-@ref Platform-WindowlessEglApplication-usage-emscripten "WindowlessEglApplication documentation"
-for more information.
+above to it via GET parameters. See the relevant section of the
+@ref platforms-html5-environment "Emscripten guide" for more information.
 
 @section magnum-al-info-example Example output
 
diff --git a/src/Magnum/Platform/Sdl2Application.h b/src/Magnum/Platform/Sdl2Application.h
index 6c32b0adb..f68f80460 100644
--- a/src/Magnum/Platform/Sdl2Application.h
+++ b/src/Magnum/Platform/Sdl2Application.h
@@ -120,8 +120,11 @@ cmake --build .
 cmake --build . --target install
 @endcode
 
-You can then open `MyApplication.html` in your browser (through webserver, e.g.
-http://localhost/emscripten/MyApplication.html).
+You can then open `MyApplication.html` in your browser (through a webserver,
+e.g. http://localhost/emscripten/MyApplication.html).
+
+Detailed information about deployment for Emscripten and all needed boilerplate
+together with a troubleshooting guide is available in @ref platforms-html5.
 
 @section Platform-Sdl2Application-bootstrap-ios Bootstrap application for iOS
 
@@ -221,50 +224,6 @@ If no other application header is included, this class is also aliased to
 @cpp Platform::Application @ce and the macro is aliased to @cpp MAGNUM_APPLICATION_MAIN() @ce
 to simplify porting.
 
-@section Platform-Sdl2Application-usage-emscripten Usage with Emscripten
-
-If you are targetting Emscripten, you need to provide HTML markup for your
-application. Template one is below or in the bootstrap application, you can
-modify it to your liking. The markup references two files,
-`EmscriptenApplication.js` and `WebApplication.css`, both are in `Platform/`
-directory in the source tree and are also installed into `share/magnum/` inside
-your Emscripten toolchain. Change `{{application}}` to name of your
-executable.
-
-@code{.html}
-
-
-  
-    Magnum Emscripten Application
-    
-    
-  
-  
-    

Magnum Emscripten Application

-
- -
Initialization...
-
- - -
- - -@endcode - -You can modify all the files to your liking, but the HTML file must contain at -least the @cb{.html} @ce enclosed in listener @cb{.html}
@ce. -The JavaScript file contains event listeners which print loading status on the -page. The status displayed in the remaining two @cb{.html}
@ce s, if they -are available. The CSS file contains rudimentary style to avoid eye bleeding. - -The application redirects all output (thus also @ref Corrade::Utility::Debug "Debug", -@ref Corrade::Utility::Warning "Warning" and @ref Corrade::Utility::Error "Error") -to JavaScript console. It's possible to pass command-line arguments to -@cpp main() @ce using GET URL parameters. For example, -`/app/?foo=bar&fizz&buzz=3` will go to the app as -@cb{.py} ['--foo', 'bar', '--fizz', '--buzz', '3'] @ce. - @section Platform-Sdl2Application-usage-ios Usage with iOS A lot of options for iOS build (such as HiDPI/Retina support, supported display diff --git a/src/Magnum/Platform/WindowlessEglApplication.h b/src/Magnum/Platform/WindowlessEglApplication.h index e5b5066a0..601de0efa 100644 --- a/src/Magnum/Platform/WindowlessEglApplication.h +++ b/src/Magnum/Platform/WindowlessEglApplication.h @@ -242,8 +242,11 @@ cmake --build . cmake --build . --target install @endcode -You can then open `MyApplication.html` in your browser (through webserver, e.g. -http://localhost/emscripten/MyApplication.html). +You can then open `MyApplication.html` in your browser (through a webserver, +e.g. http://localhost/emscripten/MyApplication.html). + +Detailed information about deployment for Emscripten and all needed boilerplate +together with a troubleshooting guide is available in @ref platforms-html5. @section Platform-WindowlessEglApplication-usage General usage @@ -278,51 +281,6 @@ MAGNUM_WINDOWLESSEGLAPPLICATION_MAIN(MyApplication) If no other application header is included, this class is also aliased to @cpp Platform::WindowlessApplication @ce and the macro is aliased to @cpp MAGNUM_WINDOWLESSAPPLICATION_MAIN() @ce to simplify porting. - -@section Platform-WindowlessEglApplication-usage-emscripten Usage with Emscripten - -If you are targetting Emscripten, you need to provide HTML markup for your -application. Template one is below or in the bootstrap application, you can -modify it to your liking. The markup references two files, -`WindowlessEmscriptenApplication.js` and `WebApplication.css`, both are in -`Platform/` directory in the source tree and are also installed into -`share/magnum/` inside your Emscripten toolchain. Change `{{application}}` -to name of your executable. - -@code{.html} - - - - Magnum Windowless Emscripten Application - - - - -

Magnum Windowless Emscripten Application

-
- -

-      
Initialization...
-
- - -
- - -@endcode - -You can modify all the files to your liking, but the HTML file must contain at -least the @cb{.html} @ce enclosed in listener @cb{.html}
@ce. -The JavaScript file contains event listeners which print loading status on the -page. The status displayed in the remaining two @cb{.html}
@ce s, if they -are available. The CSS file contains rudimentary style to avoid eye bleeding. - -The application prints all output (thus also @ref Corrade::Utility::Debug "Debug", -@ref Corrade::Utility::Warning "Warning" and @ref Corrade::Utility::Error "Error") -to the @cb{.html}
 @ce on the page. It's possible to pass command-line
-arguments to @cpp main() @ce using GET URL parameters. For example,
-`/app/?foo=bar&fizz&buzz=3` will go to the app as
-@cb{.py} ['--foo', 'bar', '--fizz', '--buzz', '3'] @ce.
 */
 class WindowlessEglApplication {
     public:
diff --git a/src/Magnum/Platform/gl-info.cpp b/src/Magnum/Platform/gl-info.cpp
index 4a0712284..75308ad6c 100644
--- a/src/Magnum/Platform/gl-info.cpp
+++ b/src/Magnum/Platform/gl-info.cpp
@@ -108,9 +108,8 @@ Arguments:
 When installing Magnum, point the `MAGNUM_DEPLOY_PREFIX` CMake variable to your
 webserver location. The Magnum Info utility is then available in a `magnum-info/`
 subdirectory of given location. You can pass all command-line arguments from
-above to it via GET parameters. See the relevant section of
-@ref Platform-WindowlessEglApplication-usage-emscripten "WindowlessEglApplication documentation"
-for more information.
+above to it via GET parameters. See the relevant section of the
+@ref platforms-html5-environment "Emscripten guide" for more information.
 
 @subsection magnum-gl-info-usage-android Usage on Android