Emscripten Docs, Materials, Learnings

[adamziel]

Emscripten lacks developer resources. We all scramble for clues and reverse engineer Emscripten code every time Playground needs an adjustment in the build pipeline. Let's centralize our efforts and use this issue as a hub for everything we learn about Emscripten.

• Compilation flags
  • There are two layers of flags: Upstream Clang flags (including some related to WebAssembly!) and Emscripten-specific flags
• Memory
  • Emscripten-built binaries are 32 bit
  • The 64 bit memory proposal is in the works
  • Meanwhile, would the -sMEMORY64=2 flag help with anything? The docs says: "The “architecture” to compile for. 0 means the default wasm32, 1 is the full end-to-end wasm64 mode, and 2 is wasm64 for clang/lld but lowered to wasm32 in Binaryen (such that it can run on wasm32 engines, while internally using i64 pointers). Assumes WASM_BIGINT."
• WASI
  • Emscripten is unlikely to support WASI. Any WASI support in Chrome will come through a third-party JavaScript integration library.
  • PHP WASM: Compile PHP to WASI #290
• Async
  • Asyncify PHP builds are unstable
  • JSPI – learnings from migrating Asyncify -> JSPI
• Filesystem
  • The JavaScript filesystem API works, but it may not get significantly more features
  • The Emscripten team heavily invests in a C-level filesystem implementation called WASMFS. It requires pthreads or JSPI.
  • milky2028/emscripten-fs-minimal repository has a few examples of WASMFS
  • OPFS Explorer enables browsing OPFS in chrome devtools
  • I don't know any prior art on synchronizing concurrent writes from multiple workers to OPFS

cc @brandonpayton @bgrgicak @mho22 @psrpinto @akirk

[bgrgicak]

Emscripten development environment setup

I had to set up a local Emscripten development environment today and it took me a while to figure it our, so I'm adding my notes here.

• Emsdk
  • Install MacOS dependencies
  • Clone Emsdk from https://github.com/emscripten-core/emsdk
  • Install Emsdk
• LLVM
  • Clone LLVM from https://github.com/llvm/llvm-project
  • Build LLVM
• Emscripten
  • Clone Emscripten from https://github.com/emscripten-core/emscripten/
  • Generate config ./emcc --generate-config
  • Update the .emscripten config
    • Add BINARYEN_ROOT path to config (YOUR-LOCAL-EMSDK-PATH/upstream/)
    • Add LLVM_ROOT path to config (YOUR-LOCAL-LLVM-PATH/build/bin/)
  • Bootstrap Emscripten ./bootstrap
  • Run Emscripten tests
    • Testing documentation
    • Single test example ./test/runner other.test_unistd_fstatfs
    • Browser tests
      • Export Chrome path export EMTEST_BROWSER='/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome' (this was my path on MacOS)
      • Single browser test example ./test/runner browser.test_offset_converte