Missing documentation for building using emscripten

[gracicot]

Describe the bug
The documentation for building bgfx to webassembly using emscripten is missing.

To Reproduce
Steps to reproduce the behavior:

1. Go to https://bkaradzic.github.io/bgfx/
2. Search for instruction for compiling to WASM using emscripten
3. Notice to lack of documentation for this supported platform

Expected behavior
A clear documentation for building to webassembly should be present. It should contain:

• The expected emscripten version
• How to enable features such as the target api platform (like webgpu, webgl)
• What command to type to build bgfx
• How to run the example in the browser

What I tried
Here's what I tried for now despite the lack of instructions, and what issues I've encountered.

First, building bgfx with genie:

• I have emscripten installed on my computer following the instructions here: https://emscripten.org/docs/getting_started/downloads.html

• Emscripten version 3.1.12

• MacOS 11.5.1 (x86_64)

• CMake 3.22 (nix)

• Ninja 1.10.2 (nix)

• Xcode version 13.2.1

• make wasm-debug

  • An error encountered:

    ==== Building bx (debug) ====
    Creating ../../wasm/obj/Debug/bx
    Creating ../../wasm/obj/Debug/bx/bx/src
    Creating ../../wasm/bin
    allocator.cpp
    /bin/sh: /em++: No such file or directory
    make[2]: *** [../../wasm/obj/Debug/bx/bx/src/allocator.o] Error 127
    make[1]: *** [bx] Error 2
    make: *** [wasm-debug] Error 2
    

  • Reason: emsdk (the supported installation instruction from emscripten) don't set the environment variable EMSCRIPTEN, and their official docker image don't set that variable either, and the make scripts assume that variable exists instead of taking em++ from PATH

  • Fix: Set manually the EMSCRIPTEN environment variable or change how bgfx.make is generated so that those lines:

    CC  = "$(EMSCRIPTEN)/emcc"
    CXX = "$(EMSCRIPTEN)/em++"
    AR  = "$(EMSCRIPTEN)/emar"
    

    becomes

    CC  = "emcc"
    CXX = "em++"
    AR  = "emar"
    

• Environment variable manually set then make wasm-debug again

  • Another error:

    ==== Building example-17-drawstress (debug) ====
    Creating ../../wasm/obj/Debug/example-17-drawstress
    Creating ../../wasm/obj/Debug/example-17-drawstress/examples/17-drawstress
    drawstress.cpp
    ../../../examples/17-drawstress/drawstress.cpp:98:24: error: no type named 'Thread' in namespace 'bx'
    int32_t threadFunc(bx::Thread* _thread, void* _userData);
                       ~~~~^
    ../../../examples/17-drawstress/drawstress.cpp:204:21: error: no type named 'Thread' in namespace 'bx'
            int32_t thread(bx::Thread* _thread)
                           ~~~~^
    ../../../examples/17-drawstress/drawstress.cpp:446:6: error: no type named 'Thread' in namespace 'bx'
            bx::Thread m_thread[5];
            ~~~~^
    ../../../examples/17-drawstress/drawstress.cpp:339:4: error: no matching function for call to 'showExampleDialog'
                            showExampleDialog(this);
                            ^~~~~~~~~~~~~~~~~
    ../../../examples/common/imgui/imgui.h:37:6: note: candidate function not viable: no known conversion from '(anonymous namespace)::ExampleDrawStress *' to 'entry::AppI *' for 1st argument
    void showExampleDialog(entry::AppI* _app, const char* _errorText = NULL);
         ^
    ../../../examples/17-drawstress/drawstress.cpp:454:24: error: no type named 'Thread' in namespace 'bx'
    int32_t threadFunc(bx::Thread* _thread, void* _userData)
                       ~~~~^
    ../../../examples/17-drawstress/drawstress.cpp:462:1: error: cannot initialize a parameter of type 'entry::AppI *' with an rvalue of type '(anonymous namespace)::ExampleDrawStress *'
    ENTRY_IMPLEMENT_MAIN(
    ^~~~~~~~~~~~~~~~~~~~~
    ../../../examples/common/entry/entry.h:31:25: note: expanded from macro 'ENTRY_IMPLEMENT_MAIN'
                            return entry::runApp(&app, _argc, _argv);   \
                                                 ^~~~
    ../../../examples/common/entry/entry.h:326:19: note: passing argument to parameter '_app' here
            int runApp(AppI* _app, int _argc, const char* const* _argv);
                             ^
    6 errors generated.
    em++: error: '/Users/grc/Workspace/github/emsdk/upstream/bin/clang++ -target wasm32-unknown-emscripten -DEMSCRIPTEN -D__EMSCRIPTEN_major__=3 -D__EMSCRIPTEN_minor__=1 -D__EMSCRIPTEN_tiny__=12 -fignore-exceptions -fvisibility=default -mllvm -combiner-global-alias-analysis=false -mllvm -enable-emscripten-sjlj -mllvm -disable-lsr -Werror=implicit-function-declaration -Xclang -iwithsysroot/include/SDL --sysroot=/Users/grc/Workspace/github/emsdk/upstream/emscripten/cache/sysroot -Xclang -iwithsysroot/include/compat -MMD -MP -MP -D__STDC_LIMIT_MACROS -D__STDC_FORMAT_MACROS -D__STDC_CONSTANT_MACROS -D_DEBUG -DENTRY_CONFIG_IMPLEMENT_MAIN=1 -DBX_CONFIG_DEBUG=1 -I../../../../bimg/include -I../../../include -I../../../3rdparty -I../../../examples/common -I../../../../bx/include -Wall -Wextra -ffast-math -fomit-frame-pointer -g3 -Werror -O2 -std=c++14 -fno-rtti -fno-exceptions -Wunused-value -Wundef -c ../../../examples/17-drawstress/drawstress.cpp -o ../../wasm/obj/Debug/example-17-drawstress/examples/17-drawstress/drawstress.o' failed (returned 1)
    make[2]: *** [../../wasm/obj/Debug/example-17-drawstress/examples/17-drawstress/drawstress.o] Error 1
    make[1]: *** [example-17-drawstress] Error 2
    make: *** [wasm-debug] Error 2
    

• Without knowing how to disable threading with genie, I decided to use bgfx.cmake which exposes the option

• Cloned the bgfx.cmake repo and moved in it

  • mkdir build && cd build

  • cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/emsdk/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake -G"Ninja Multi-Config" -DBGFX_CONFIG_MULTITHREADED=OFF -DBGFX_INSTALL_EXAMPLES=ON

  • The -DBGFX_INSTALL_EXAMPLES=ON was required to build the examples, even if -DDBGFX_BUILD_EXAMPLES=ON is set

  • cmake --build . --config=Debug

  • Error with the following output

    [12/92] Linking CXX executable Debug/example-35-dynamic.js
    FAILED: Debug/example-35-dynamic.js
    : && workspace/emsdk/upstream/emscripten/em++ -g  CMakeFiles/example-35-dynamic.dir/Debug/bgfx/examples/35-dynamic/dynamic.cpp.o -o Debug/example-35-dynamic.js  Debug/libexample-common.a  -s PRECISE_F32=1  -s TOTAL_MEMORY=268435456  --memory-init-file 1  Debug/libbgfx.a  Debug/libbimg.a  Debug/libastc-codec.a  Debug/libastc.a  Debug/libedtaa3.a  Debug/libetc1.a  Debug/libetc2.a  Debug/libiqa.a  Debug/libsquish.a  Debug/libnvtt.a  Debug/libpvrtc.a  Debug/libtinyexr.a  Debug/libdear-imgui.a  Debug/libbx.a  -ldl  -lrt  Debug/libmeshoptimizer.a  -lX11 && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/font workspace/bgfx.cmake/build/Debug/font && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/images workspace/bgfx.cmake/build/Debug/images && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/meshes workspace/bgfx.cmake/build/Debug/meshes && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/shaders workspace/bgfx.cmake/build/Debug/shaders && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/text workspace/bgfx.cmake/build/Debug/text && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/textures workspace/bgfx.cmake/build/Debug/textures
    error: undefined symbol: emscripten_webgl2_get_proc_address (referenced by top-level compiled C/C++ code)
    warning: Link with `-sLLD_REPORT_UNDEFINED` to get more information on undefined symbols
    warning: To disable errors for undefined symbols use `-sERROR_ON_UNDEFINED_SYMBOLS=0`
    warning: _emscripten_webgl2_get_proc_address may need to be added to EXPORTED_FUNCTIONS if it arrives from a system library
    Error: Aborting compilation due to previous errors
    em++: error: 'workspace/emsdk/node/14.18.2_64bit/bin/node workspace/emsdk/upstream/emscripten/src/compiler.js /var/folders/vy/xby6hsz97j184x77rhcsnfk80000gn/T/tmpe6xeqdzf.json' failed (returned 1)
    [13/92] Linking CXX executable Debug/example-34-mvs.js
    FAILED: Debug/example-34-mvs.js
    : && workspace/emsdk/upstream/emscripten/em++ -g  CMakeFiles/example-34-mvs.dir/Debug/bgfx/examples/34-mvs/mvs.cpp.o -o Debug/example-34-mvs.js  Debug/libexample-common.a  -s PRECISE_F32=1  -s TOTAL_MEMORY=268435456  --memory-init-file 1  Debug/libbgfx.a  Debug/libbimg.a  Debug/libastc-codec.a  Debug/libastc.a  Debug/libedtaa3.a  Debug/libetc1.a  Debug/libetc2.a  Debug/libiqa.a  Debug/libsquish.a  Debug/libnvtt.a  Debug/libpvrtc.a  Debug/libtinyexr.a  Debug/libdear-imgui.a  Debug/libbx.a  -ldl  -lrt  Debug/libmeshoptimizer.a  -lX11 && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/font workspace/bgfx.cmake/build/Debug/font && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/images workspace/bgfx.cmake/build/Debug/images && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/meshes workspace/bgfx.cmake/build/Debug/meshes && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/shaders workspace/bgfx.cmake/build/Debug/shaders && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/text workspace/bgfx.cmake/build/Debug/text && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/textures workspace/bgfx.cmake/build/Debug/textures
    error: undefined symbol: emscripten_webgl2_get_proc_address (referenced by top-level compiled C/C++ code)
    warning: Link with `-sLLD_REPORT_UNDEFINED` to get more information on undefined symbols
    warning: To disable errors for undefined symbols use `-sERROR_ON_UNDEFINED_SYMBOLS=0`
    warning: _emscripten_webgl2_get_proc_address may need to be added to EXPORTED_FUNCTIONS if it arrives from a system library
    Error: Aborting compilation due to previous errors
    em++: error: 'workspace/emsdk/node/14.18.2_64bit/bin/node workspace/emsdk/upstream/emscripten/src/compiler.js /var/folders/vy/xby6hsz97j184x77rhcsnfk80000gn/T/tmpvkv9tp_p.json' failed (returned 1)
    [14/92] Linking CXX executable Debug/example-38-bloom.js
    FAILED: Debug/example-38-bloom.js
    : && workspace/emsdk/upstream/emscripten/em++ -g  CMakeFiles/example-38-bloom.dir/Debug/bgfx/examples/38-bloom/bloom.cpp.o -o Debug/example-38-bloom.js  Debug/libexample-common.a  -s PRECISE_F32=1  -s TOTAL_MEMORY=268435456  --memory-init-file 1  Debug/libbgfx.a  Debug/libbimg.a  Debug/libastc-codec.a  Debug/libastc.a  Debug/libedtaa3.a  Debug/libetc1.a  Debug/libetc2.a  Debug/libiqa.a  Debug/libsquish.a  Debug/libnvtt.a  Debug/libpvrtc.a  Debug/libtinyexr.a  Debug/libdear-imgui.a  Debug/libbx.a  -ldl  -lrt  Debug/libmeshoptimizer.a  -lX11 && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/font workspace/bgfx.cmake/build/Debug/font && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/images workspace/bgfx.cmake/build/Debug/images && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/meshes workspace/bgfx.cmake/build/Debug/meshes && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/shaders workspace/bgfx.cmake/build/Debug/shaders && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/text workspace/bgfx.cmake/build/Debug/text && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/textures workspace/bgfx.cmake/build/Debug/textures
    error: undefined symbol: emscripten_webgl2_get_proc_address (referenced by top-level compiled C/C++ code)
    warning: Link with `-sLLD_REPORT_UNDEFINED` to get more information on undefined symbols
    warning: To disable errors for undefined symbols use `-sERROR_ON_UNDEFINED_SYMBOLS=0`
    warning: _emscripten_webgl2_get_proc_address may need to be added to EXPORTED_FUNCTIONS if it arrives from a system library
    Error: Aborting compilation due to previous errors
    em++: error: 'workspace/emsdk/node/14.18.2_64bit/bin/node workspace/emsdk/upstream/emscripten/src/compiler.js /var/folders/vy/xby6hsz97j184x77rhcsnfk80000gn/T/tmp3ls2tznp.json' failed (returned 1)
    [15/92] Linking CXX executable Debug/example-31-rsm.js
    FAILED: Debug/example-31-rsm.js
    : && workspace/emsdk/upstream/emscripten/em++ -g  CMakeFiles/example-31-rsm.dir/Debug/bgfx/examples/31-rsm/reflectiveshadowmap.cpp.o -o Debug/example-31-rsm.js  Debug/libexample-common.a  -s PRECISE_F32=1  -s TOTAL_MEMORY=268435456  --memory-init-file 1  Debug/libbgfx.a  Debug/libbimg.a  Debug/libastc-codec.a  Debug/libastc.a  Debug/libedtaa3.a  Debug/libetc1.a  Debug/libetc2.a  Debug/libiqa.a  Debug/libsquish.a  Debug/libnvtt.a  Debug/libpvrtc.a  Debug/libtinyexr.a  Debug/libdear-imgui.a  Debug/libbx.a  -ldl  -lrt  Debug/libmeshoptimizer.a  -lX11 && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/font workspace/bgfx.cmake/build/Debug/font && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/images workspace/bgfx.cmake/build/Debug/images && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/meshes workspace/bgfx.cmake/build/Debug/meshes && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/shaders workspace/bgfx.cmake/build/Debug/shaders && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/text workspace/bgfx.cmake/build/Debug/text && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/textures workspace/bgfx.cmake/build/Debug/textures
    error: undefined symbol: emscripten_webgl2_get_proc_address (referenced by top-level compiled C/C++ code)
    warning: Link with `-sLLD_REPORT_UNDEFINED` to get more information on undefined symbols
    warning: To disable errors for undefined symbols use `-sERROR_ON_UNDEFINED_SYMBOLS=0`
    warning: _emscripten_webgl2_get_proc_address may need to be added to EXPORTED_FUNCTIONS if it arrives from a system library
    Error: Aborting compilation due to previous errors
    em++: error: 'workspace/emsdk/node/14.18.2_64bit/bin/node workspace/emsdk/upstream/emscripten/src/compiler.js /var/folders/vy/xby6hsz97j184x77rhcsnfk80000gn/T/tmpwxo9h843.json' failed (returned 1)
    [16/92] Linking CXX executable Debug/example-30-picking.js
    FAILED: Debug/example-30-picking.js
    : && workspace/emsdk/upstream/emscripten/em++ -g  CMakeFiles/example-30-picking.dir/Debug/bgfx/examples/30-picking/picking.cpp.o -o Debug/example-30-picking.js  Debug/libexample-common.a  -s PRECISE_F32=1  -s TOTAL_MEMORY=268435456  --memory-init-file 1  Debug/libbgfx.a  Debug/libbimg.a  Debug/libastc-codec.a  Debug/libastc.a  Debug/libedtaa3.a  Debug/libetc1.a  Debug/libetc2.a  Debug/libiqa.a  Debug/libsquish.a  Debug/libnvtt.a  Debug/libpvrtc.a  Debug/libtinyexr.a  Debug/libdear-imgui.a  Debug/libbx.a  -ldl  -lrt  Debug/libmeshoptimizer.a  -lX11 && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/font workspace/bgfx.cmake/build/Debug/font && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/images workspace/bgfx.cmake/build/Debug/images && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/meshes workspace/bgfx.cmake/build/Debug/meshes && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/shaders workspace/bgfx.cmake/build/Debug/shaders && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/text workspace/bgfx.cmake/build/Debug/text && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/textures workspace/bgfx.cmake/build/Debug/textures
    error: undefined symbol: emscripten_webgl2_get_proc_address (referenced by top-level compiled C/C++ code)
    warning: Link with `-sLLD_REPORT_UNDEFINED` to get more information on undefined symbols
    warning: To disable errors for undefined symbols use `-sERROR_ON_UNDEFINED_SYMBOLS=0`
    warning: _emscripten_webgl2_get_proc_address may need to be added to EXPORTED_FUNCTIONS if it arrives from a system library
    Error: Aborting compilation due to previous errors
    em++: error: 'workspace/emsdk/node/14.18.2_64bit/bin/node workspace/emsdk/upstream/emscripten/src/compiler.js /var/folders/vy/xby6hsz97j184x77rhcsnfk80000gn/T/tmppc6zm_v3.json' failed (returned 1)
    [17/92] Linking CXX executable Debug/example-33-pom.js
    FAILED: Debug/example-33-pom.js
    : && workspace/emsdk/upstream/emscripten/em++ -g  CMakeFiles/example-33-pom.dir/Debug/bgfx/examples/33-pom/pom.cpp.o -o Debug/example-33-pom.js  Debug/libexample-common.a  -s PRECISE_F32=1  -s TOTAL_MEMORY=268435456  --memory-init-file 1  Debug/libbgfx.a  Debug/libbimg.a  Debug/libastc-codec.a  Debug/libastc.a  Debug/libedtaa3.a  Debug/libetc1.a  Debug/libetc2.a  Debug/libiqa.a  Debug/libsquish.a  Debug/libnvtt.a  Debug/libpvrtc.a  Debug/libtinyexr.a  Debug/libdear-imgui.a  Debug/libbx.a  -ldl  -lrt  Debug/libmeshoptimizer.a  -lX11 && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/font workspace/bgfx.cmake/build/Debug/font && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/images workspace/bgfx.cmake/build/Debug/images && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/meshes workspace/bgfx.cmake/build/Debug/meshes && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/shaders workspace/bgfx.cmake/build/Debug/shaders && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/text workspace/bgfx.cmake/build/Debug/text && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/textures workspace/bgfx.cmake/build/Debug/textures
    error: undefined symbol: emscripten_webgl2_get_proc_address (referenced by top-level compiled C/C++ code)
    warning: Link with `-sLLD_REPORT_UNDEFINED` to get more information on undefined symbols
    warning: To disable errors for undefined symbols use `-sERROR_ON_UNDEFINED_SYMBOLS=0`
    warning: _emscripten_webgl2_get_proc_address may need to be added to EXPORTED_FUNCTIONS if it arrives from a system library
    Error: Aborting compilation due to previous errors
    em++: error: 'workspace/emsdk/node/14.18.2_64bit/bin/node workspace/emsdk/upstream/emscripten/src/compiler.js /var/folders/vy/xby6hsz97j184x77rhcsnfk80000gn/T/tmp1oenky49.json' failed (returned 1)
    [18/92] Linking CXX executable Debug/example-39-assao.js
    FAILED: Debug/example-39-assao.js
    : && workspace/emsdk/upstream/emscripten/em++ -g  CMakeFiles/example-39-assao.dir/Debug/bgfx/examples/39-assao/assao.cpp.o -o Debug/example-39-assao.js  Debug/libexample-common.a  -s PRECISE_F32=1  -s TOTAL_MEMORY=268435456  --memory-init-file 1  Debug/libbgfx.a  Debug/libbimg.a  Debug/libastc-codec.a  Debug/libastc.a  Debug/libedtaa3.a  Debug/libetc1.a  Debug/libetc2.a  Debug/libiqa.a  Debug/libsquish.a  Debug/libnvtt.a  Debug/libpvrtc.a  Debug/libtinyexr.a  Debug/libdear-imgui.a  Debug/libbx.a  -ldl  -lrt  Debug/libmeshoptimizer.a  -lX11 && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/font workspace/bgfx.cmake/build/Debug/font && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/images workspace/bgfx.cmake/build/Debug/images && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/meshes workspace/bgfx.cmake/build/Debug/meshes && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/shaders workspace/bgfx.cmake/build/Debug/shaders && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/text workspace/bgfx.cmake/build/Debug/text && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/textures workspace/bgfx.cmake/build/Debug/textures
    error: undefined symbol: emscripten_webgl2_get_proc_address (referenced by top-level compiled C/C++ code)
    warning: Link with `-sLLD_REPORT_UNDEFINED` to get more information on undefined symbols
    warning: To disable errors for undefined symbols use `-sERROR_ON_UNDEFINED_SYMBOLS=0`
    warning: _emscripten_webgl2_get_proc_address may need to be added to EXPORTED_FUNCTIONS if it arrives from a system library
    Error: Aborting compilation due to previous errors
    em++: error: 'workspace/emsdk/node/14.18.2_64bit/bin/node workspace/emsdk/upstream/emscripten/src/compiler.js /var/folders/vy/xby6hsz97j184x77rhcsnfk80000gn/T/tmpxczefbgd.json' failed (returned 1)
    [19/92] Linking CXX executable Debug/example-32-particles.js
    FAILED: Debug/example-32-particles.js
    : && workspace/emsdk/upstream/emscripten/em++ -g  CMakeFiles/example-32-particles.dir/Debug/bgfx/examples/32-particles/particles.cpp.o -o Debug/example-32-particles.js  Debug/libexample-common.a  -s PRECISE_F32=1  -s TOTAL_MEMORY=268435456  --memory-init-file 1  Debug/libbgfx.a  Debug/libbimg.a  Debug/libastc-codec.a  Debug/libastc.a  Debug/libedtaa3.a  Debug/libetc1.a  Debug/libetc2.a  Debug/libiqa.a  Debug/libsquish.a  Debug/libnvtt.a  Debug/libpvrtc.a  Debug/libtinyexr.a  Debug/libdear-imgui.a  Debug/libbx.a  -ldl  -lrt  Debug/libmeshoptimizer.a  -lX11 && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/font workspace/bgfx.cmake/build/Debug/font && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/images workspace/bgfx.cmake/build/Debug/images && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/meshes workspace/bgfx.cmake/build/Debug/meshes && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/shaders workspace/bgfx.cmake/build/Debug/shaders && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/text workspace/bgfx.cmake/build/Debug/text && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/textures workspace/bgfx.cmake/build/Debug/textures
    error: undefined symbol: emscripten_webgl2_get_proc_address (referenced by top-level compiled C/C++ code)
    warning: Link with `-sLLD_REPORT_UNDEFINED` to get more information on undefined symbols
    warning: To disable errors for undefined symbols use `-sERROR_ON_UNDEFINED_SYMBOLS=0`
    warning: _emscripten_webgl2_get_proc_address may need to be added to EXPORTED_FUNCTIONS if it arrives from a system library
    Error: Aborting compilation due to previous errors
    em++: error: 'workspace/emsdk/node/14.18.2_64bit/bin/node workspace/emsdk/upstream/emscripten/src/compiler.js /var/folders/vy/xby6hsz97j184x77rhcsnfk80000gn/T/tmpiolvpk36.json' failed (returned 1)
    [20/92] Linking CXX executable Debug/example-36-sky.js
    FAILED: Debug/example-36-sky.js
    : && workspace/emsdk/upstream/emscripten/em++ -g  CMakeFiles/example-36-sky.dir/Debug/bgfx/examples/36-sky/sky.cpp.o -o Debug/example-36-sky.js  Debug/libexample-common.a  -s PRECISE_F32=1  -s TOTAL_MEMORY=268435456  --memory-init-file 1  Debug/libbgfx.a  Debug/libbimg.a  Debug/libastc-codec.a  Debug/libastc.a  Debug/libedtaa3.a  Debug/libetc1.a  Debug/libetc2.a  Debug/libiqa.a  Debug/libsquish.a  Debug/libnvtt.a  Debug/libpvrtc.a  Debug/libtinyexr.a  Debug/libdear-imgui.a  Debug/libbx.a  -ldl  -lrt  Debug/libmeshoptimizer.a  -lX11 && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/font workspace/bgfx.cmake/build/Debug/font && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/images workspace/bgfx.cmake/build/Debug/images && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/meshes workspace/bgfx.cmake/build/Debug/meshes && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/shaders workspace/bgfx.cmake/build/Debug/shaders && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/text workspace/bgfx.cmake/build/Debug/text && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/textures workspace/bgfx.cmake/build/Debug/textures
    error: undefined symbol: emscripten_webgl2_get_proc_address (referenced by top-level compiled C/C++ code)
    warning: Link with `-sLLD_REPORT_UNDEFINED` to get more information on undefined symbols
    warning: To disable errors for undefined symbols use `-sERROR_ON_UNDEFINED_SYMBOLS=0`
    warning: _emscripten_webgl2_get_proc_address may need to be added to EXPORTED_FUNCTIONS if it arrives from a system library
    Error: Aborting compilation due to previous errors
    em++: error: 'workspace/emsdk/node/14.18.2_64bit/bin/node workspace/emsdk/upstream/emscripten/src/compiler.js /var/folders/vy/xby6hsz97j184x77rhcsnfk80000gn/T/tmpsuk4w16i.json' failed (returned 1)
    [21/92] Linking CXX executable Debug/example-40-svt.js
    FAILED: Debug/example-40-svt.js
    : && workspace/emsdk/upstream/emscripten/em++ -g  CMakeFiles/example-40-svt.dir/Debug/bgfx/examples/40-svt/svt.cpp.o CMakeFiles/example-40-svt.dir/Debug/bgfx/examples/40-svt/vt.cpp.o -o Debug/example-40-svt.js  Debug/libexample-common.a  -s PRECISE_F32=1  -s TOTAL_MEMORY=268435456  --memory-init-file 1  Debug/libbgfx.a  Debug/libbimg.a  Debug/libastc-codec.a  Debug/libastc.a  Debug/libedtaa3.a  Debug/libetc1.a  Debug/libetc2.a  Debug/libiqa.a  Debug/libsquish.a  Debug/libnvtt.a  Debug/libpvrtc.a  Debug/libtinyexr.a  Debug/libdear-imgui.a  Debug/libbx.a  -ldl  -lrt  Debug/libmeshoptimizer.a  -lX11 && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/font workspace/bgfx.cmake/build/Debug/font && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/images workspace/bgfx.cmake/build/Debug/images && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/meshes workspace/bgfx.cmake/build/Debug/meshes && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/shaders workspace/bgfx.cmake/build/Debug/shaders && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/text workspace/bgfx.cmake/build/Debug/text && cd workspace/bgfx.cmake/build && /nix/store/hpld3wyf2ap36gld4sxa2hc2brrlkjfn-cmake-3.22.3/bin/cmake -E create_symlink workspace/bgfx.cmake/bgfx/examples/runtime/textures workspace/bgfx.cmake/build/Debug/textures
    error: undefined symbol: emscripten_webgl2_get_proc_address (referenced by top-level compiled C/C++ code)
    warning: Link with `-sLLD_REPORT_UNDEFINED` to get more information on undefined symbols
    warning: To disable errors for undefined symbols use `-sERROR_ON_UNDEFINED_SYMBOLS=0`
    warning: _emscripten_webgl2_get_proc_address may need to be added to EXPORTED_FUNCTIONS if it arrives from a system library
    Error: Aborting compilation due to previous errors
    em++: error: 'workspace/emsdk/node/14.18.2_64bit/bin/node workspace/emsdk/upstream/emscripten/src/compiler.js /var/folders/vy/xby6hsz97j184x77rhcsnfk80000gn/T/tmpkedszl0i.json' failed (returned 1)
    ninja: build stopped: subcommand failed.
    

What are the instructions to build the example using web assembly? What are the requirements to start developing with bgfx using emscripten? It seems like the current documentation is lacking.

If someone knows how to build for the webassembly platform, instructions on how to build the examples would be highly appreciated 🙏 I am willing to help with documentation efforts if I can successfully build bgfx and examples with emscripten.

[bkaradzic]

Just set EMSCRIPTEN variable to where Emscripten is installed...