Emscripten for Debian
=====================


Tools installed to $PATH
------------------------

Emscripten upstream expects all its tools to be executed
from same common project directory.

Debian packaging of Emscripten instead provide tools
installed to $PATH.


Code cache
----------

Emscripten includes a set of system libraries
which are compiled as needed, and cached for later reuse.

(in principle these system libraries could be pre-compiled
and provided as Debian packages,
but attempts at suppressing upstream treating them as only cached,
opportunistically attempting to dynamically rebuilding
and failing when in read-only directories,
have so far been unsuccessful).

Never run emscripten tools as root,
as they may then litter system directories with cache files.


LLVM
----

Emscripten use external tool collection "LLVM" as compiler backend.

Unfortunately, Emscripten uses unreleased snapshot of LLVM
where Debian provide only official releases of LLVM.

Debian packaging of Emscripten has been superficially patched
to use latest released and Debian-packaged LLVM.

Using features requiring newer LLVM may lead to errors like this:

  * Function addresses with offsets not supported
  * TLS symbol is undefined, but TLS symbols cannot yet be imported
  * unknown argument: '-mrelaxed-simd'


Closure compiler
----------------

Emscripten use external tool "closure compiler" to optimize for size.

Unfortunately, Debian-packaged closure compiler is too old
(see <https://bugs.debian.org/916145>).

Using too old closure compiler may lead to errors like this:

  * No such file or directory: '--max_old_space_size=8192'

Avoid closure compiler either by compiling without optimization,
or (possibly, not well tested) by passing option "--closure=0".


 -- Jonas Smedegaard <dr@jones.dk>  Fri, 26 Nov 2021 10:09:02 +0100
