Magnum & Emscripten

README.md

Magnum and Emscripten

This gist will demonstrate how to build the simplest example of Magnum with Emscripten, and run it in your browser, using With PowerShell for Windows, Linux and MacOS.

Translated to Alanese from Magnum Emscripten on Windows

References

• Magnum and HTML5
• Magnum EmscriptenApplication

1. Ready

# Check prerequisites
if ((get-command "cmake"      -erroraction silentlycontinue) -eq $null) { write-host CMake not found! }
if ((get-command "ninja"      -erroraction silentlycontinue) -eq $null) { write-host Ninja not found! }
if ((get-command "em++"       -erroraction silentlycontinue) -eq $null) { write-host Emscripten not found! }
if ((get-command "corrade-rc" -erroraction silentlycontinue) -eq $null) { write-host corrade-rc not found! }
if ((get-command "python"     -erroraction silentlycontinue) -eq $null) { write-host Python not found! }

Toubleshooting

I don't have Emscripten installed

Here's how to install it.

git clone https://github.com/emscripten-core/emsdk --branch 1.39.18 --single-branch
cd emsdk
./emsdk install latest
./emsdk activate latest
cd ..

Emscripten not found, but I have it installed

Then you need to activate the environment first.

. path/to/emscripten/emsdk_env.ps1

corrade-rc not found

Funnily enough, to build with Magnum for Emscripten, you need to build Corrade for Desktop first. Corrade provides an executable called corrade-rc that you'll need accessible on PATH prior to continuing.

This is a fresh Ubuntu 18.04 Docker container

Then you'll need a few things.

apt install -y git python ninja-build cmake build-essential

2. Set

$THIS_GIST="https://gist.github.com/e7078b6c646cefa7e532549963d6c2fa.git"
git clone $THIS_GIST magnum_emscripten
cd magnum_emscripten
. ./clone_magnum.ps1
. ./build_magnum.ps1

See below what these .ps1 files do.

3. Go

mkdir web
cd web
cp ../index.html ./
cp $env:EMSDK/upstream/emscripten/system/share/magnum/* ./
cp ../magnum-examples/build-emc/Release/bin/* ./
python -m http.server
# Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/)

• Visit http://localhost:8000
• Profit

build_magnum.ps1

# Remember current working directory
pushd

$BUILD_DIR="build-emc"
if (-not (test-path "./corrade/$BUILD_DIR"))          { mkdir ./corrade/$BUILD_DIR }
if (-not (test-path "./magnum/$BUILD_DIR"))           { mkdir ./magnum/$BUILD_DIR }
if (-not (test-path "./magnum-plugins/$BUILD_DIR"))   { mkdir ./magnum-plugins/$BUILD_DIR }
if (-not (test-path "./magnum-extras/$BUILD_DIR"))    { mkdir ./magnum-extras/$BUILD_DIR }
if (-not (test-path "./magnum-examples/$BUILD_DIR"))  { mkdir ./magnum-examples/$BUILD_DIR }

# Where Magnum example apps are to be deployed
$DEPLOY_PREFIX="${pwd}/deploy"
if (-not (test-path "${DEPLOY_PREFIX}")) { mkdir "${DEPLOY_PREFIX}" }

# This converts the emscripten path set in your environment by emcmdprompt by replacing all \ with /
# Only relevant on Windows, but doesn't hurt other OSes
$EMSCRIPTEN_PREFIX=$env:EMSDK.replace("\\", "/") + "/upstream/emscripten"

# 1. Set things up..
$CMAKE_CMD=(`
"cmake .. -G Ninja " +`
"    -DCMAKE_PREFIX_PATH='$env:PREFIX_PATH' " +`
"    -DCMAKE_INSTALL_PREFIX='$EMSCRIPTEN_PREFIX/system' " +`
"    -DCMAKE_BUILD_TYPE=Release " +`
# "    -DCMAKE_BUILD_TYPE=Debug " +`
"    -DCMAKE_TOOLCHAIN_FILE='../toolchains/generic/Emscripten-wasm.cmake' " +`
"    -DEMSCRIPTEN_PREFIX='$EMSCRIPTEN_PREFIX'"
)
$CMAKE_BUILD_CMD="cmake --build . --target install"

$CORRADE_CMD = $CMAKE_CMD +`
    " -DWITH_TESTSUITE=OFF" +`
    " -DBUILD_DEPRECATED=OFF"

$MAGNUM_CMD = $CMAKE_CMD +`
    " -DTARGET_GLES2=OFF" +`
    " -DWITH_EMSCRIPTENAPPLICATION=ON" +`
    " -DWITH_SDL2APPLICATION=ON" +`
    " -DWITH_MESHTOOLS=ON" +`
    " -DWITH_PRIMITIVES=ON" +`
    " -DWITH_OBJIMPORTER=ON" +`
    " -DWITH_TGAIMPORTER=ON" +`
    " -DWITH_SHADERS=ON" +`
    " -DWITH_TEXT=ON" +`
    " -DWITH_AUDIO=ON" +`
    " -DWITH_WAVAUDIOIMPORTER=ON" +`
    " -DWITH_ANYIMAGEIMPORTER=ON" +`
    " -DBUILD_DEPRECATED=OFF"

$PLUGINS_CMD = $CMAKE_CMD +`
    " -DWITH_OPENGEXIMPORTER=ON" +`
    " -DWITH_STBTRUETYPEFONT=ON" +`
    " -DBUILD_DEPRECATED=OFF" +`
    " -DWITH_TINYGLTFIMPORTER=ON"

$EXAMPLES_CMD = $CMAKE_CMD +`
    " -DWITH_TEXTUREDTRIANGLE_EXAMPLE=ON" +`
    " -DWITH_AUDIO_EXAMPLE=OFF" +`
    " -DMAGNUM_DEPLOY_PREFIX='${DEPLOY_PREFIX}'"

# 2. Kick things off
cd ./corrade/$BUILD_DIR
invoke-expression $CORRADE_CMD
invoke-expression $CMAKE_BUILD_CMD

cd ../../magnum/$BUILD_DIR
invoke-expression $MAGNUM_CMD
invoke-expression $CMAKE_BUILD_CMD

cd ../../magnum-plugins/$BUILD_DIR
invoke-expression $PLUGINS_CMD
invoke-expression $CMAKE_BUILD_CMD

cd ../../magnum-examples/$BUILD_DIR
invoke-expression $EXAMPLES_CMD
invoke-expression $CMAKE_BUILD_CMD

# Restore current working directory
popd

clone_magnum.ps1

# Clone the 2020.06 release for all
git clone --recurse-submodules git://github.com/mosra/corrade            --branch v2020.06
git clone --recurse-submodules git://github.com/mosra/magnum             --branch v2020.06
git clone --recurse-submodules git://github.com/mosra/magnum-plugins     --branch v2020.06
git clone --recurse-submodules git://github.com/mosra/magnum-integration --branch v2020.06
git clone --recurse-submodules git://github.com/mosra/magnum-extras      --branch v2020.06
git clone --recurse-submodules git://github.com/mosra/magnum-examples    --branch v2020.06

index.html

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8" />
  <title>Magnum Emscripten Application</title>
  <link rel="stylesheet" href="WebApplication.css" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
</head>
<body>
  <h1>Magnum Emscripten Application</h1>
  <div id="container">
    <div id="sizer"><div id="expander"><div id="listener">
      <canvas id="canvas"></canvas>
      <div id="status">Initialization...</div>
      <div id="status-description"></div>
      <script src="EmscriptenApplication.js"></script>
      <script async="async" src="magnum-triangle.js"></script>
    </div></div></div>
  </div>
</body>
</html>

This gist should naturally lead to questions like..

1. Help! My WASM is 10 mb! How do I make a smaller, release-build?
2. That final cp step references multiple paths, how do I change where files are installed?
3. Ok, so I've built a pre-made example. How can I build my project?
4. How do I style the HTML website? Do I need to use the supplied Magnum CSS?