doc/languages-frameworks/emscripten.section.md

   1 # Emscripten {#emscripten}
   2
   3 [Emscripten](https://github.com/kripken/emscripten): An LLVM-to-JavaScript Compiler
   4
   5 This section of the manual covers how to use `emscripten` in nixpkgs.
   6
   7 Minimal requirements:
   8
   9 * nix
  10 * nixpkgs
  11
  12 Modes of use of `emscripten`:
  13
  14 * **Imperative usage** (on the command line):
  15
  16    If you want to work with `emcc`, `emconfigure` and `emmake` as you are used to from Ubuntu and similar distributions you can use these commands:
  17
  18     * `nix-env -f "<nixpkgs>" -iA emscripten`
  19     * `nix-shell -p emscripten`
  20
  21 * **Declarative usage**:
  22
  23     This mode is far more power full since this makes use of `nix` for dependency management of emscripten libraries and targets by using the `mkDerivation` which is implemented by `pkgs.emscriptenStdenv` and `pkgs.buildEmscriptenPackage`. The source for the packages is in `pkgs/top-level/emscripten-packages.nix` and the abstraction behind it in `pkgs/development/em-modules/generic/default.nix`. From the root of the nixpkgs repository:
  24     * build and install all packages:
  25         * `nix-env -iA emscriptenPackages`
  26
  27     * dev-shell for zlib implementation hacking:
  28         * `nix-shell -A emscriptenPackages.zlib`
  29
  30 ## Imperative usage {#imperative-usage}
  31
  32 A few things to note:
  33
  34 * `export EMCC_DEBUG=2` is nice for debugging
  35 * `~/.emscripten`, the build artifact cache sometimes creates issues and needs to be removed from time to time
  36
  37 ## Declarative usage {#declarative-usage}
  38
  39 Let's see two different examples from `pkgs/top-level/emscripten-packages.nix`:
  40
  41 * `pkgs.zlib.override`
  42 * `pkgs.buildEmscriptenPackage`
  43
  44 Both are interesting concepts.
  45
  46 A special requirement of the `pkgs.buildEmscriptenPackage` is the `doCheck = true` is a default meaning that each emscriptenPackage requires a `checkPhase` implemented.
  47
  48 * Use `export EMCC_DEBUG=2` from within a emscriptenPackage's `phase` to get more detailed debug output what is going wrong.
  49 * ~/.emscripten cache is requiring us to set `HOME=$TMPDIR` in individual phases. This makes compilation slower but also makes it more deterministic.
  50
  51 ### Usage 1: pkgs.zlib.override {#usage-1-pkgs.zlib.override}
  52
  53 This example uses `zlib` from nixpkgs but instead of compiling **C** to **ELF** it compiles **C** to **JS** since we were using `pkgs.zlib.override` and changed stdenv to `pkgs.emscriptenStdenv`. A few adaptions and hacks were set in place to make it working. One advantage is that when `pkgs.zlib` is updated, it will automatically update this package as well. However, this can also be the downside...
  54
  55 See the `zlib` example:
  56
  57     zlib = (pkgs.zlib.override {
  58       stdenv = pkgs.emscriptenStdenv;
  59     }).overrideDerivation
  60     (old: rec {
  61       buildInputs = old.buildInputs ++ [ pkg-config ];
  62       # we need to reset this setting!
  63       NIX_CFLAGS_COMPILE="";
  64       configurePhase = ''
  65         # FIXME: Some tests require writing at $HOME
  66         HOME=$TMPDIR
  67         runHook preConfigure
  68
  69         #export EMCC_DEBUG=2
  70         emconfigure ./configure --prefix=$out --shared
  71
  72         runHook postConfigure
  73       '';
  74       dontStrip = true;
  75       outputs = [ "out" ];
  76       buildPhase = ''
  77         emmake make
  78       '';
  79       installPhase = ''
  80         emmake make install
  81       '';
  82       checkPhase = ''
  83         echo "================= testing zlib using node ================="
  84
  85         echo "Compiling a custom test"
  86         set -x
  87         emcc -O2 -s EMULATE_FUNCTION_POINTER_CASTS=1 test/example.c -DZ_SOLO \
  88         libz.so.${old.version} -I . -o example.js
  89
  90         echo "Using node to execute the test"
  91         ${pkgs.nodejs}/bin/node ./example.js
  92
  93         set +x
  94         if [ $? -ne 0 ]; then
  95           echo "test failed for some reason"
  96           exit 1;
  97         else
  98           echo "it seems to work! very good."
  99         fi
 100         echo "================= /testing zlib using node ================="
 101       '';
 102
 103       postPatch = pkgs.lib.optionalString pkgs.stdenv.isDarwin ''
 104         substituteInPlace configure \
 105           --replace '/usr/bin/libtool' 'ar' \
 106           --replace 'AR="libtool"' 'AR="ar"' \
 107           --replace 'ARFLAGS="-o"' 'ARFLAGS="-r"'
 108       '';
 109     });
 110
 111 ### Usage 2: pkgs.buildEmscriptenPackage {#usage-2-pkgs.buildemscriptenpackage}
 112
 113 This `xmlmirror` example features a emscriptenPackage which is defined completely from this context and no `pkgs.zlib.override` is used.
 114
 115     xmlmirror = pkgs.buildEmscriptenPackage rec {
 116       name = "xmlmirror";
 117
 118       buildInputs = [ pkg-config autoconf automake libtool gnumake libxml2 nodejs openjdk json_c ];
 119       nativeBuildInputs = [ pkg-config zlib ];
 120
 121       src = pkgs.fetchgit {
 122         url = "https://gitlab.com/odfplugfest/xmlmirror.git";
 123         rev = "4fd7e86f7c9526b8f4c1733e5c8b45175860a8fd";
 124         sha256 = "1jasdqnbdnb83wbcnyrp32f36w3xwhwp0wq8lwwmhqagxrij1r4b";
 125       };
 126
 127       configurePhase = ''
 128         rm -f fastXmlLint.js*
 129         # a fix for ERROR:root:For asm.js, TOTAL_MEMORY must be a multiple of 16MB, was 234217728
 130         # https://gitlab.com/odfplugfest/xmlmirror/issues/8
 131         sed -e "s/TOTAL_MEMORY=234217728/TOTAL_MEMORY=268435456/g" -i Makefile.emEnv
 132         # https://github.com/kripken/emscripten/issues/6344
 133         # https://gitlab.com/odfplugfest/xmlmirror/issues/9
 134         sed -e "s/\$(JSONC_LDFLAGS) \$(ZLIB_LDFLAGS) \$(LIBXML20_LDFLAGS)/\$(JSONC_LDFLAGS) \$(LIBXML20_LDFLAGS) \$(ZLIB_LDFLAGS) /g" -i Makefile.emEnv
 135         # https://gitlab.com/odfplugfest/xmlmirror/issues/11
 136         sed -e "s/-o fastXmlLint.js/-s EXTRA_EXPORTED_RUNTIME_METHODS='[\"ccall\", \"cwrap\"]' -o fastXmlLint.js/g" -i Makefile.emEnv
 137       '';
 138
 139       buildPhase = ''
 140         HOME=$TMPDIR
 141         make -f Makefile.emEnv
 142       '';
 143
 144       outputs = [ "out" "doc" ];
 145
 146       installPhase = ''
 147         mkdir -p $out/share
 148         mkdir -p $doc/share/${name}
 149
 150         cp Demo* $out/share
 151         cp -R codemirror-5.12 $out/share
 152         cp fastXmlLint.js* $out/share
 153         cp *.xsd $out/share
 154         cp *.js $out/share
 155         cp *.xhtml $out/share
 156         cp *.html $out/share
 157         cp *.json $out/share
 158         cp *.rng $out/share
 159         cp README.md $doc/share/${name}
 160       '';
 161       checkPhase = ''
 162
 163       '';
 164     };
 165
 166 ### Declarative debugging {#declarative-debugging}
 167
 168 Use `nix-shell -I nixpkgs=/some/dir/nixpkgs -A emscriptenPackages.libz` and from there you can go trough the individual steps. This makes it easy to build a good `unit test` or list the files of the project.
 169
 170 1. `nix-shell -I nixpkgs=/some/dir/nixpkgs -A emscriptenPackages.libz`
 171 2. `cd /tmp/`
 172 3. `unpackPhase`
 173 4. cd libz-1.2.3
 174 5. `configurePhase`
 175 6. `buildPhase`
 176 7. ... happy hacking...
 177
 178 ## Summary {#summary}
 179
 180 Using this toolchain makes it easy to leverage `nix` from NixOS, MacOSX or even Windows (WSL+ubuntu+nix). This toolchain is reproducible, behaves like the rest of the packages from nixpkgs and contains a set of well working examples to learn and adapt from.
 181
 182 If in trouble, ask the maintainers.