pyrox.dev
1# Emscripten {#emscripten}
2
3[Emscripten](https://github.com/kripken/emscripten): An LLVM-to-JavaScript Compiler
4
5This section of the manual covers how to use `emscripten` in nixpkgs.
6
7Minimal requirements:
8
9* nix
10* nixpkgs
11
12Modes 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 -i 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`.
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
32A 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
39Let's see two different examples from `pkgs/top-level/emscripten-packages.nix`:
40
41* `pkgs.zlib.override`
42* `pkgs.buildEmscriptenPackage`
43
44Both are interesting concepts.
45
46A 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
53This 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
55See 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
113This `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
168Use `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
1701. `nix-shell -I nixpkgs=/some/dir/nixpkgs -A emscriptenPackages.libz`
1712. `cd /tmp/`
1723. `unpackPhase`
1734. cd libz-1.2.3
1745. `configurePhase`
1756. `buildPhase`
1767. ... happy hacking...
177
178## Summary {#summary}
179
180Using 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
182If in trouble, ask the maintainers.