static/README.wasm.md

   1 # Support for Emscripten Cross Build
   2
   3 This subdirectory provides support for building LibreOffice as WASM, with the Emscripten toolchain.
   4
   5 You can build LibreOffice for WASM for two separate purposes: 1)
   6 Either to produce a WASM binary of LibreOffice as such, using Qt5 for
   7 its GUI, or 2) just compiling LibreOffice core ("LibreOffice
   8 Technology") to WASM without any UI for use in other software that
   9 provides the UI, like Collabora Online built as WASM.
  10
  11 The first purpose was the original reason for the WASM port and this
  12 document was originally written with that in mind. For the second
  13 purpose, look towards the end of the document for the section
  14 "Building headless LibreOffice as WASM for use in another product".
  15
  16 ## Status of LibreOffice as WASM with Qt
  17
  18 The build generates a Writer-only LO build. You should be able to run either
  19
  20     $ emrun --serve_after_close instdir/program/qt_soffice.html
  21     $ emrun --serve_after_close workdir/LinkTarget/Executable/qt_vcldemo.html
  22     $ emrun --serve_after_close workdir/LinkTarget/Executable/qt_wasm-qt5-mandelbrot.html
  23
  24 REMINDER: Always start new tabs in the browser, reload might fail / cache!
  25 INFO: latest browser won't work anymore with 0.0.0.0 and need 127.0.0.1.
  26
  27 ## Setup for the LO WASM build (with Qt)
  28
  29 We're using Qt 5.15.2 with Emscripten 3.1.46. There are a bunch of Qt patches
  30 to fix the most grave bugs. Also there's rapid development in Emscripten, so
  31 using another version often causes arbitrary problems.
  32
  33 - See below under Docker build for another build option
  34
  35 ### Setup emscripten
  36
  37 <https://emscripten.org/docs/getting_started/index.html>
  38
  39     git clone https://github.com/emscripten-core/emsdk.git
  40     ./emsdk install 3.1.46
  41     ./emsdk activate 3.1.46
  42
  43 Example `bashrc` scriptlet:
  44
  45     EMSDK_ENV=$HOME/Development/libreoffice/git_emsdk/emsdk_env.sh
  46     [ -f "$EMSDK_ENV" ] && \. "$EMSDK_ENV" 1>/dev/null 2>&1
  47
  48 ### Setup Qt
  49
  50 <https://doc.qt.io/qt-5/wasm.html>
  51
  52 Most of the information from <https://doc.qt.io/qt-6/wasm.html> is still valid for Qt5;
  53 generally the Qt6 WASM documentation is much better, because it incorporated many
  54 information from the Qt Wiki.
  55
  56 FWIW: Qt 5.15 LTS is not maintained publicly and Qt WASM has quite a few bugs. Most
  57 WASM fixes from Qt 6 are needed for Qt 5.15 too. Allotropia offers a Qt repository
  58 with the necessary patches cherry-picked.
  59
  60 With "-opensource -confirm-license" you agree to the open source license.
  61
  62     git clone https://github.com/allotropia/qt5.git
  63     cd qt5
  64     git checkout v5.15.2+wasm
  65     ./init-repository --module-subset=qtbase
  66     ./configure -opensource -confirm-license -xplatform wasm-emscripten -feature-thread -prefix <whatever>
  67     make -j<CORES> module-qtbase
  68
  69 Optionally you can add the configure flag "-compile-examples". But then you also have to
  70 patch at least mkspecs/wasm-emscripten/qmake.conf with EXIT_RUNTIME=0, otherwise they will
  71 fail to run. In addition, building with examples will break with some of them, but at that
  72 point Qt already works and also most examples. Or just skip them. Other interesting flags
  73 might be "-nomake tests -no-pch -ccache".
  74
  75 Linking takes quite a long time, because emscripten-finalize rewrites the whole WASM files with
  76 some options. This way the LO WASM possibly needs 64GB RAM. For faster link times add
  77 "-s WASM_BIGINT=1", change to ASSERTIONS=1 and use -g3 to prevent rewriting the WASM file and
  78 generating source maps (see emscripten.py, finalize_wasm, and avoid modify_wasm = True). This is
  79 just needed for Qt examples, as LO already uses the correct flags!
  80
  81 It's needed to install Qt5 to the chosen prefix. Else LO won't find all needed files in the
  82 right place. For installation you can do
  83
  84     make -j<CORES> install
  85 or
  86     make -j8 -C qtbase/src install_subtargets
  87
  88 Current Qt fails to start the demo webserver: <https://bugreports.qt.io/browse/QTCREATORBUG-24072>
  89
  90 Use `emrun --serve_after_close` to run Qt WASM demos.
  91
  92 ### Setup LO
  93
  94 `autogen.sh` is patched to use emconfigure. That basically sets various
  95 environment vars, especially `EMMAKEN_JUST_CONFIGURE`, which will create the
  96 correct output file names, checked by `configure` (`a.out`).
  97
  98 There's a distro config for WASM, but it just provides --host=wasm32-local-emscripten, which
  99 should be enough setup. The build itself is a cross build and the cross-toolset just depends
 100 on a minimal toolset (gcc, libc-dev, flex, bison); all else is build from source, because the
 101 final result is not depending on the build system at all.
 102
 103 Recommended configure setup is thusly:
 104
 105 * grab defaults
 106     `--with-distro=LibreOfficeWASM32`
 107
 108 * local config
 109     `QT5DIR=/dir/of/qt5/install/prefix`
 110
 111 * if you want to use ccache on both sides of the build
 112     `--with-build-platform-configure-options=--enable-ccache`
 113     `--enable-ccache`
 114
 115 FWIW: it's also possible to build an almost static Linux LibreOffice by just using
 116 --disable-dynloading --enable-customtarget-components. System externals are still
 117 linked dynamically, but everything else is static.
 118
 119 #### Experimental (AKA currently broken) WASM exception + SjLj build
 120
 121 You can build LO with WASM exceptions, which should be "much" faster then the JS
 122 based Emscripten EH handling. For setjmp / longjmp (SjLj) used by the PNG and JPEG
 123 libraries error handling, this needs Emscripten 3.1.3+. That builds, but execution
 124 still fails early with a signature mismatch call to Task::UpdateMinPeriod in LO's
 125 job scheduler code. Unfortunately the build also needs a Qt build with
 126 "-s SUPPORT_LONGJMP=wasm", which is incompatible with the JS EH + SjLj.
 127
 128 The LO configure flag is simply an additional --enable-wasm-exceptions. Qt5 can
 129 be patched in qtbase/mkspecs/wasm-emscripten/qmake.conf with the addition of
 130
 131     QMAKE_CFLAGS += -s SUPPORT_LONGJMP=wasm
 132     QMAKE_CXXFLAGS += -s SUPPORT_LONGJMP=wasm
 133
 134 ### "Deploying" soffice.wasm
 135
 136     tar -chf wasm.tar --xform 's/.*program/lo-wasm/' instdir/program/soffice.* \
 137         instdir/program/qt*
 138
 139 Your HTTP server needs to provide additional headers:
 140 * add_header Cross-Origin-Opener-Policy same-origin
 141 * add_header Cross-Origin-Embedder-Policy require-corp
 142
 143 The default html to use should be qt_soffice.html
 144
 145 ### Debugging setup
 146
 147 Since a few months you can use DWARF information embedded by LLVM into the WASM
 148 to debug WASM in Chrome. You need to enable an experimental feature and install
 149 an additional extension. The whole setup is described in:
 150
 151 https://developer.chrome.com/blog/wasm-debugging-2020/
 152
 153 This way you don't need source maps (much faster linking!) and can resolve local
 154 WASM variables to C++ names!
 155
 156 Per default, the WASM debug build splits the DWARF information into an additional
 157 WASM file, postfixed '.debug.wasm'.
 158
 159 ### Using Docker to cross-build with emscripten
 160
 161 If you prefer a controlled environment (sadly emsdk install/activate
 162 is _not_ stable over time, as e.g. nodejs versions evolve), that is
 163 easy to replicate across different machines - consider the docker
 164 images we're providing.
 165
 166 Config/setup file see
 167 <https://git.libreoffice.org/lode/+/ccb36979563635b51215477455953252c99ec013>
 168
 169 Run
 170
 171     docker-compose build
 172
 173 in the lode/docker dir to get the container prepared. Run
 174
 175     PARALLELISM=4 BUILD_OPTIONS= BUILD_TARGET=build docker-compose run --rm \
 176         -e PARALLELISM -e BUILD_TARGET -e BUILD_OPTIONS builder
 177
 178 to perform an actual `srcdir != builddir` build; the container mounts
 179 checked-out git repo and output dir via `docker-compose.yml` (so make
 180 sure the path names there match your setup):
 181
 182 The lode setup expects, inside the lode/docker subdir, the following directories:
 183
 184 - core (`git checkout`)
 185 - workdir (the output dir - gets written into)
 186 - cache (`ccache tree`)
 187 - tarballs (external project tarballs gets written and cached there)
 188
 189
 190 ## Ideas for an UNO bridge implementation
 191
 192 My post to Discord #emscripten:
 193
 194 "I'm looking for a way to do an abstract call
 195 from one WASM C++ object to another WASM C++ object, so like FFI / WebIDL,
 196 just within WASM. All my code is C++ and normally I have bridge code, with
 197 assembler to implement the function call /RTTI and exception semantics of the
 198 specified platform. Code is at
 199 <https://cgit.freedesktop.org/libreoffice/core/tree/bridges/source/cpp_uno>.
 200 I've read a bit about `call_indirect` and stuff, but I don't have yet a good
 201 idea, how I could implement this (and  there is an initial feature/wasm branch
 202 for the interested). I probably need some fixed lookup table, like on iOS,
 203 because AFAIK you can't dynamically generate code in WASM. So any pointers or
 204 ideas for an implementation? I can disassemble some minimalistic WASM example
 205 and read clang code for `WASM_EmscriptenInvoke`, but if there were some
 206 standalone code or documentation I'm missing, that would be nice to know."
 207
 208 We basically would go the same way then the other backends. Write the bridge in
 209 C++, which is probably largely boilerplate code, but the function call in WAT
 210 (<https://github.com/WebAssembly/wabt>) based on the LLVM WASM calling
 211 conventions in `WASM_EmscriptenInvoke`. I didn't get a reply to that question for
 212 hours. Maybe I'll open an Emscripten issue, if we really have to implement
 213 this.
 214
 215 WASM dynamic dispatch:
 216
 217 - <https://fitzgeraldnick.com/2018/04/26/how-does-dynamic-dispatch-work-in-wasm.html>
 218
 219 ### UNO bindings with Embind
 220
 221 Right now there's a very rough implementation in place. With lots of different
 222 bits unimplemented. And it _might_ be leaking memory. i.e. Lots of room for
 223 improvement! ;)
 224
 225 Some usage examples through javascript of the current implementation:
 226 ```js
 227 // inserts a string at the start of the Writer document.
 228 let uno = init_unoembind_uno(Module);
 229 let css = uno.com.sun.star;
 230 xModel = Module.getCurrentModelFromViewSh();
 231 xTextDocument = new css.text.XTextDocument(xModel);
 232 xText = xTextDocument.getText();
 233 xSimpleText = new css.text.XSimpleText(xText);
 234 xTextCursor = xSimpleText.createTextCursor();
 235 xTextRange = new css.text.XTextRange(xTextCursor);
 236 xTextRange.setString("string here!");
 237 xModel.delete(); xTextDocument.delete(); xText.delete(); xSimpleText.delete(); xTextCursor.delete(); xTextRange.delete();
 238 ```
 239
 240 ```js
 241 // changes each paragraph of the Writer document to a random color.
 242 let uno = init_unoembind_uno(Module);
 243 let css = uno.com.sun.star;
 244 xModel = Module.getCurrentModelFromViewSh();
 245 xEnumAccess = new css.container.XEnumerationAccess(xText);
 246 xParaEnumeration = xEnumAccess.createEnumeration();
 247
 248 while (xParaEnumeration.hasMoreElements()) {
 249     xParagraph = new css.text.XTextRange(xParaEnumeration.nextElement().get());
 250     if (xParagraph.$is()) {
 251         xParaProps = new css.beans.XPropertySet(xParagraph);
 252         let color = new Module.uno_Any(
 253             Module.uno_Type.Long(), Math.floor(Math.random() * 0xFFFFFF));
 254         xParaProps.setPropertyValue("CharColor", color);
 255         color.delete();
 256     }
 257 }
 258 ```
 259
 260
 261
 262 ## Tools for problem diagnosis
 263
 264 * `nm -s` should list the symbols in the archive, based on the index generated by ranlib.
 265   If you get linking errors that archive has no index.
 266
 267
 268 ## Emscripten filesystem access with threads
 269
 270 This is closed, but not really fixed IMHO:
 271
 272 - <https://github.com/emscripten-core/emscripten/issues/3922>
 273
 274 ## Dynamic libraries `/` modules in emscripten
 275
 276 There is a good summary in:
 277
 278 - <https://bugreports.qt.io/browse/QTBUG-63925>
 279
 280 Summary: you can't use modules and threads.
 281
 282 This is mentioned at the end of:
 283
 284 - <https://github.com/emscripten-core/emscripten/wiki/Linking>
 285
 286 The usage of `MAIN_MODULE` and `SIDE_MODULE` has other problems, a major one IMHO is symbol resolution at runtime only.
 287 So this works really more like plugins in the sense of symbol resolution without dependencies `/` rpath.
 288
 289 There is some clang-level dynamic-linking in progress (WASM dlload). The following link is already a bit old,
 290 but I found it a god summary of problems to expect:
 291
 292 - <https://iandouglasscott.com/2019/07/18/experimenting-with-webassembly-dynamic-linking-with-clang/>
 293
 294
 295 ## Mixed information, links, problems, TODO
 296
 297 More info on Qt WASM emscripten pthreads:
 298
 299 - <https://wiki.qt.io/Qt_for_WebAssembly#Multithreading_Support>
 300
 301 WASM needs `-pthread` at compile, not just link time for atomics support. Alternatively you can provide
 302 `-s USE_PTHREADS=1`, but both don't seem to work reliable, so best provide both.
 303 <https://github.com/emscripten-core/emscripten/issues/10370>
 304
 305 The output file must have the prefix .o, otherwise the WASM files will get a
 306 `node.js` shebang (!) and ranlib won't be able to index the library (link errors).
 307
 308 Qt with threads has further memory limit. From Qt configure:
 309 ````
 310 Project MESSAGE: Setting PTHREAD_POOL_SIZE to 4
 311 Project MESSAGE: Setting TOTAL_MEMORY to 1GB
 312 ````
 313
 314 You can actually allocate 4GB:
 315
 316 - <https://bugzilla.mozilla.org/show_bug.cgi?id=1392234>
 317
 318 LO uses a nested event loop to run dialogs in general, but that won't work, because you can't drive
 319 the browser event loop. like VCL does with the system event loop in the various VCL backends.
 320 Changing this will need some major work (basically dropping Application::Execute).
 321
 322 But with the know problems with exceptions and threads, this might change:
 323
 324 - <https://github.com/emscripten-core/emscripten/pull/11518>
 325 - <https://github.com/emscripten-core/emscripten/issues/11503>
 326 - <https://github.com/emscripten-core/emscripten/issues/11233>
 327 - <https://github.com/emscripten-core/emscripten/issues/12035>
 328
 329 We're also using emconfigure at the moment. Originally I patched emscripten, because it
 330 wouldn't create the correct a.out file for C++ configure tests. Later I found that
 331 the `emconfigure` sets `EMMAKEN_JUST_CONFIGURE` to work around the problem.
 332
 333 ICU bug:
 334
 335 - <https://github.com/emscripten-core/emscripten/issues/10129>
 336
 337 Alternative, probably:
 338
 339 - <https://developer.mozilla.org/de/docs/Web/JavaScript/Reference/Global_Objects/Intl>
 340
 341 There is a wasm64, but that still uses 32bit pointers!
 342
 343 Old outdated docs:
 344
 345 - <https://wiki.documentfoundation.org/Development/Emscripten>
 346
 347 Reverted patch:
 348
 349 - <https://cgit.freedesktop.org/libreoffice/core/commit/?id=0e21f6619c72f1e17a7b0a52b6317810973d8a3e>
 350
 351 Generally <https://emscripten.org/docs/porting>:
 352
 353 - <https://emscripten.org/docs/porting/guidelines/api_limitations.html#api-limitations>
 354 - <https://emscripten.org/docs/porting/files/file_systems_overview.html#file-system-overview>
 355 - <https://emscripten.org/docs/porting/pthreads.html>
 356 - <https://emscripten.org/docs/porting/emscripten-runtime-environment.html>
 357
 358 This will be interesting:
 359
 360 - <https://emscripten.org/docs/getting_started/FAQ.html#how-do-i-run-an-event-loop>
 361
 362 This didn't help much yet:
 363
 364 - <https://github.com/emscripten-ports>
 365
 366 Emscripten supports standalone WASI binaries:
 367
 368 - <https://github.com/emscripten-core/emscripten/wiki/WebAssembly-Standalone>
 369 - <https://www.qt.io/qt-examples-for-webassembly>
 370 - <http://qtandeverything.blogspot.com/2017/06/qt-for-web-assembly.html>
 371 - <http://qtandeverything.blogspot.com/2020/>
 372 - <https://emscripten.org/docs/api_reference/Filesystem-API.html>
 373 - <https://discuss.python.org/t/add-a-webassembly-wasm-runtime/3957/12>
 374 - <http://git.savannah.gnu.org/cgit/config.git>
 375 - <https://webassembly.org/specs/>
 376 - <https://developer.chrome.com/docs/native-client/>
 377 - <https://emscripten.org/docs/getting_started/downloads.html>
 378 - <https://github.com/openpgpjs/openpgpjs/blob/master/README.md#getting-started>
 379 - <https://developer.mozilla.org/en-US/docs/WebAssembly/Using_the_JavaScript_API>
 380 - <https://github.com/bytecodealliance/wasmtime/blob/main/docs/WASI-intro.md>
 381 - <https://www.ip6.li/de/security/x.509_kochbuch/openssl-fuer-webassembly-compilieren>
 382 - <https://emscripten.org/docs/introducing_emscripten/about_emscripten.html#about-emscripten-porting-code>
 383 - <https://emscripten.org/docs/compiling/Building-Projects.html>
 384
 385 ## Building headless LibreOffice as WASM for use in another product
 386
 387 ### Set up Emscripten
 388
 389 Follow the instructions in the first part of this document.
 390
 391 ### No Qt needed.
 392
 393 You don't need any dependencies other than those that normally are
 394 downloaded and compiled when building LibreOffice.
 395
 396 ### Set up LO
 397
 398 For instance, this autogen.input works for me:
 399
 400 `--disable-debug`
 401 `--enable-sal-log`
 402 `--disable-crashdump`
 403 `--host=wasm32-local-emscripten`
 404 `--disable-gui`
 405 `--with-main-module=writer`
 406
 407 For building LO core for use in COWASM, it is known to work to use
 408 Emscripten 3.1.30 (and not just 2.0.31 which is what the LO+Qt5 work
 409 has been using in the past).
 410
 411 ### That's all
 412
 413 After all, in this case you are building LO core headless for it to be used by other software.
 414
 415 Note that a soffice.wasm will be built, but that is just because of
 416 how the makefilery has been set up. We do need the soffice.data file
 417 that contains the in-memory file system needed by the LibreOffice
 418 Technology core code during run-time, though. That is at the moment
 419 built as a side-effect when building soffice.wasm.