Emscripten Docs, Materials, Learnings

[adamziel]

Emscripten lacks developer resources. Since we often reverse engineer Emscripten code, let's centralize our efforts, document our learnings, 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.
  • adamziel/emscripten-wasmfs-demo 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