mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-09-29 07:32:58 +00:00
Merge pull request #258595 from fricklerhandwerk/doc-emscripten
Emscripten docs: reword and remove mention of `nix-env`
This commit is contained in:
commit
643419f02b
2
.github/CODEOWNERS
vendored
2
.github/CODEOWNERS
vendored
@ -149,6 +149,8 @@
|
|||||||
# C compilers
|
# C compilers
|
||||||
/pkgs/development/compilers/gcc @amjoseph-nixpkgs
|
/pkgs/development/compilers/gcc @amjoseph-nixpkgs
|
||||||
/pkgs/development/compilers/llvm @RaitoBezarius
|
/pkgs/development/compilers/llvm @RaitoBezarius
|
||||||
|
/pkgs/development/compilers/emscripten @raitobezarius
|
||||||
|
/doc/languages-frameworks/emscripten.section.md @raitobezarius
|
||||||
|
|
||||||
# Audio
|
# Audio
|
||||||
/nixos/modules/services/audio/botamusique.nix @mweinelt
|
/nixos/modules/services/audio/botamusique.nix @mweinelt
|
||||||
|
@ -2,168 +2,159 @@
|
|||||||
|
|
||||||
[Emscripten](https://github.com/kripken/emscripten): An LLVM-to-JavaScript Compiler
|
[Emscripten](https://github.com/kripken/emscripten): An LLVM-to-JavaScript Compiler
|
||||||
|
|
||||||
This section of the manual covers how to use `emscripten` in nixpkgs.
|
If you want to work with `emcc`, `emconfigure` and `emmake` as you are used to from Ubuntu and similar distributions,
|
||||||
|
|
||||||
Minimal requirements:
|
```console
|
||||||
|
nix-shell -p emscripten
|
||||||
* nix
|
```
|
||||||
* nixpkgs
|
|
||||||
|
|
||||||
Modes of use of `emscripten`:
|
|
||||||
|
|
||||||
* **Imperative usage** (on the command line):
|
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
* `nix-env -f "<nixpkgs>" -iA emscripten`
|
|
||||||
* `nix-shell -p emscripten`
|
|
||||||
|
|
||||||
* **Declarative usage**:
|
|
||||||
|
|
||||||
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:
|
|
||||||
* build and install all packages:
|
|
||||||
* `nix-env -iA emscriptenPackages`
|
|
||||||
|
|
||||||
* dev-shell for zlib implementation hacking:
|
|
||||||
* `nix-shell -A emscriptenPackages.zlib`
|
|
||||||
|
|
||||||
## Imperative usage {#imperative-usage}
|
|
||||||
|
|
||||||
A few things to note:
|
A few things to note:
|
||||||
|
|
||||||
* `export EMCC_DEBUG=2` is nice for debugging
|
* `export EMCC_DEBUG=2` is nice for debugging
|
||||||
* `~/.emscripten`, the build artifact cache sometimes creates issues and needs to be removed from time to time
|
* The build artifact cache in `~/.emscripten` sometimes creates issues and needs to be removed from time to time
|
||||||
|
|
||||||
## Declarative usage {#declarative-usage}
|
## Examples {#declarative-usage}
|
||||||
|
|
||||||
Let's see two different examples from `pkgs/top-level/emscripten-packages.nix`:
|
Let's see two different examples from `pkgs/top-level/emscripten-packages.nix`:
|
||||||
|
|
||||||
* `pkgs.zlib.override`
|
* `pkgs.zlib.override`
|
||||||
* `pkgs.buildEmscriptenPackage`
|
* `pkgs.buildEmscriptenPackage`
|
||||||
|
|
||||||
Both are interesting concepts.
|
A special requirement of the `pkgs.buildEmscriptenPackage` is the `doCheck = true`.
|
||||||
|
This means each Emscripten package requires that a [`checkPhase`](#ssec-check-phase) is implemented.
|
||||||
|
|
||||||
A special requirement of the `pkgs.buildEmscriptenPackage` is the `doCheck = true` is a default meaning that each emscriptenPackage requires a `checkPhase` implemented.
|
* Use `export EMCC_DEBUG=2` from within a phase to get more detailed debug output what is going wrong.
|
||||||
|
* The cache at `~/.emscripten` requires to set `HOME=$TMPDIR` in individual phases.
|
||||||
|
This makes compilation slower but also more deterministic.
|
||||||
|
|
||||||
* Use `export EMCC_DEBUG=2` from within a emscriptenPackage's `phase` to get more detailed debug output what is going wrong.
|
::: {.example #usage-1-pkgs.zlib.override}
|
||||||
* ~/.emscripten cache is requiring us to set `HOME=$TMPDIR` in individual phases. This makes compilation slower but also makes it more deterministic.
|
|
||||||
|
|
||||||
### Usage 1: pkgs.zlib.override {#usage-1-pkgs.zlib.override}
|
# Using `pkgs.zlib.override {}`
|
||||||
|
|
||||||
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...
|
This example uses `zlib` from Nixpkgs, but instead of compiling **C** to **ELF** it compiles **C** to **JavaScript** since we were using `pkgs.zlib.override` and changed `stdenv` to `pkgs.emscriptenStdenv`.
|
||||||
|
|
||||||
See the `zlib` example:
|
A few adaptions and hacks were put in place to make it work.
|
||||||
|
One advantage is that when `pkgs.zlib` is updated, it will automatically update this package as well.
|
||||||
|
|
||||||
zlib = (pkgs.zlib.override {
|
|
||||||
stdenv = pkgs.emscriptenStdenv;
|
|
||||||
}).overrideAttrs
|
|
||||||
(old: rec {
|
|
||||||
buildInputs = old.buildInputs ++ [ pkg-config ];
|
|
||||||
# we need to reset this setting!
|
|
||||||
env = (old.env or { }) // { NIX_CFLAGS_COMPILE = ""; };
|
|
||||||
configurePhase = ''
|
|
||||||
# FIXME: Some tests require writing at $HOME
|
|
||||||
HOME=$TMPDIR
|
|
||||||
runHook preConfigure
|
|
||||||
|
|
||||||
#export EMCC_DEBUG=2
|
```nix
|
||||||
emconfigure ./configure --prefix=$out --shared
|
(pkgs.zlib.override {
|
||||||
|
stdenv = pkgs.emscriptenStdenv;
|
||||||
|
}).overrideAttrs
|
||||||
|
(old: rec {
|
||||||
|
buildInputs = old.buildInputs ++ [ pkg-config ];
|
||||||
|
# we need to reset this setting!
|
||||||
|
env = (old.env or { }) // { NIX_CFLAGS_COMPILE = ""; };
|
||||||
|
configurePhase = ''
|
||||||
|
# FIXME: Some tests require writing at $HOME
|
||||||
|
HOME=$TMPDIR
|
||||||
|
runHook preConfigure
|
||||||
|
|
||||||
runHook postConfigure
|
#export EMCC_DEBUG=2
|
||||||
'';
|
emconfigure ./configure --prefix=$out --shared
|
||||||
dontStrip = true;
|
|
||||||
outputs = [ "out" ];
|
|
||||||
buildPhase = ''
|
|
||||||
emmake make
|
|
||||||
'';
|
|
||||||
installPhase = ''
|
|
||||||
emmake make install
|
|
||||||
'';
|
|
||||||
checkPhase = ''
|
|
||||||
echo "================= testing zlib using node ================="
|
|
||||||
|
|
||||||
echo "Compiling a custom test"
|
runHook postConfigure
|
||||||
set -x
|
'';
|
||||||
emcc -O2 -s EMULATE_FUNCTION_POINTER_CASTS=1 test/example.c -DZ_SOLO \
|
dontStrip = true;
|
||||||
libz.so.${old.version} -I . -o example.js
|
outputs = [ "out" ];
|
||||||
|
buildPhase = ''
|
||||||
|
emmake make
|
||||||
|
'';
|
||||||
|
installPhase = ''
|
||||||
|
emmake make install
|
||||||
|
'';
|
||||||
|
checkPhase = ''
|
||||||
|
echo "================= testing zlib using node ================="
|
||||||
|
|
||||||
echo "Using node to execute the test"
|
echo "Compiling a custom test"
|
||||||
${pkgs.nodejs}/bin/node ./example.js
|
set -x
|
||||||
|
emcc -O2 -s EMULATE_FUNCTION_POINTER_CASTS=1 test/example.c -DZ_SOLO \
|
||||||
|
libz.so.${old.version} -I . -o example.js
|
||||||
|
|
||||||
set +x
|
echo "Using node to execute the test"
|
||||||
if [ $? -ne 0 ]; then
|
${pkgs.nodejs}/bin/node ./example.js
|
||||||
echo "test failed for some reason"
|
|
||||||
exit 1;
|
|
||||||
else
|
|
||||||
echo "it seems to work! very good."
|
|
||||||
fi
|
|
||||||
echo "================= /testing zlib using node ================="
|
|
||||||
'';
|
|
||||||
|
|
||||||
postPatch = pkgs.lib.optionalString pkgs.stdenv.isDarwin ''
|
set +x
|
||||||
substituteInPlace configure \
|
if [ $? -ne 0 ]; then
|
||||||
--replace '/usr/bin/libtool' 'ar' \
|
echo "test failed for some reason"
|
||||||
--replace 'AR="libtool"' 'AR="ar"' \
|
exit 1;
|
||||||
--replace 'ARFLAGS="-o"' 'ARFLAGS="-r"'
|
else
|
||||||
'';
|
echo "it seems to work! very good."
|
||||||
});
|
fi
|
||||||
|
echo "================= /testing zlib using node ================="
|
||||||
|
'';
|
||||||
|
|
||||||
### Usage 2: pkgs.buildEmscriptenPackage {#usage-2-pkgs.buildemscriptenpackage}
|
postPatch = pkgs.lib.optionalString pkgs.stdenv.isDarwin ''
|
||||||
|
substituteInPlace configure \
|
||||||
|
--replace '/usr/bin/libtool' 'ar' \
|
||||||
|
--replace 'AR="libtool"' 'AR="ar"' \
|
||||||
|
--replace 'ARFLAGS="-o"' 'ARFLAGS="-r"'
|
||||||
|
'';
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
This `xmlmirror` example features a emscriptenPackage which is defined completely from this context and no `pkgs.zlib.override` is used.
|
:::{.example #usage-2-pkgs.buildemscriptenpackage}
|
||||||
|
|
||||||
xmlmirror = pkgs.buildEmscriptenPackage rec {
|
# Using `pkgs.buildEmscriptenPackage {}`
|
||||||
name = "xmlmirror";
|
|
||||||
|
|
||||||
buildInputs = [ pkg-config autoconf automake libtool gnumake libxml2 nodejs openjdk json_c ];
|
This `xmlmirror` example features an Emscripten package that is defined completely from this context and no `pkgs.zlib.override` is used.
|
||||||
nativeBuildInputs = [ pkg-config zlib ];
|
|
||||||
|
|
||||||
src = pkgs.fetchgit {
|
```nix
|
||||||
url = "https://gitlab.com/odfplugfest/xmlmirror.git";
|
pkgs.buildEmscriptenPackage rec {
|
||||||
rev = "4fd7e86f7c9526b8f4c1733e5c8b45175860a8fd";
|
name = "xmlmirror";
|
||||||
hash = "sha256-i+QgY+5PYVg5pwhzcDnkfXAznBg3e8sWH2jZtixuWsk=";
|
|
||||||
};
|
|
||||||
|
|
||||||
configurePhase = ''
|
buildInputs = [ pkg-config autoconf automake libtool gnumake libxml2 nodejs openjdk json_c ];
|
||||||
rm -f fastXmlLint.js*
|
nativeBuildInputs = [ pkg-config zlib ];
|
||||||
# a fix for ERROR:root:For asm.js, TOTAL_MEMORY must be a multiple of 16MB, was 234217728
|
|
||||||
# https://gitlab.com/odfplugfest/xmlmirror/issues/8
|
|
||||||
sed -e "s/TOTAL_MEMORY=234217728/TOTAL_MEMORY=268435456/g" -i Makefile.emEnv
|
|
||||||
# https://github.com/kripken/emscripten/issues/6344
|
|
||||||
# https://gitlab.com/odfplugfest/xmlmirror/issues/9
|
|
||||||
sed -e "s/\$(JSONC_LDFLAGS) \$(ZLIB_LDFLAGS) \$(LIBXML20_LDFLAGS)/\$(JSONC_LDFLAGS) \$(LIBXML20_LDFLAGS) \$(ZLIB_LDFLAGS) /g" -i Makefile.emEnv
|
|
||||||
# https://gitlab.com/odfplugfest/xmlmirror/issues/11
|
|
||||||
sed -e "s/-o fastXmlLint.js/-s EXTRA_EXPORTED_RUNTIME_METHODS='[\"ccall\", \"cwrap\"]' -o fastXmlLint.js/g" -i Makefile.emEnv
|
|
||||||
'';
|
|
||||||
|
|
||||||
buildPhase = ''
|
src = pkgs.fetchgit {
|
||||||
HOME=$TMPDIR
|
url = "https://gitlab.com/odfplugfest/xmlmirror.git";
|
||||||
make -f Makefile.emEnv
|
rev = "4fd7e86f7c9526b8f4c1733e5c8b45175860a8fd";
|
||||||
'';
|
hash = "sha256-i+QgY+5PYVg5pwhzcDnkfXAznBg3e8sWH2jZtixuWsk=";
|
||||||
|
};
|
||||||
|
|
||||||
outputs = [ "out" "doc" ];
|
configurePhase = ''
|
||||||
|
rm -f fastXmlLint.js*
|
||||||
|
# a fix for ERROR:root:For asm.js, TOTAL_MEMORY must be a multiple of 16MB, was 234217728
|
||||||
|
# https://gitlab.com/odfplugfest/xmlmirror/issues/8
|
||||||
|
sed -e "s/TOTAL_MEMORY=234217728/TOTAL_MEMORY=268435456/g" -i Makefile.emEnv
|
||||||
|
# https://github.com/kripken/emscripten/issues/6344
|
||||||
|
# https://gitlab.com/odfplugfest/xmlmirror/issues/9
|
||||||
|
sed -e "s/\$(JSONC_LDFLAGS) \$(ZLIB_LDFLAGS) \$(LIBXML20_LDFLAGS)/\$(JSONC_LDFLAGS) \$(LIBXML20_LDFLAGS) \$(ZLIB_LDFLAGS) /g" -i Makefile.emEnv
|
||||||
|
# https://gitlab.com/odfplugfest/xmlmirror/issues/11
|
||||||
|
sed -e "s/-o fastXmlLint.js/-s EXTRA_EXPORTED_RUNTIME_METHODS='[\"ccall\", \"cwrap\"]' -o fastXmlLint.js/g" -i Makefile.emEnv
|
||||||
|
'';
|
||||||
|
|
||||||
installPhase = ''
|
buildPhase = ''
|
||||||
mkdir -p $out/share
|
HOME=$TMPDIR
|
||||||
mkdir -p $doc/share/${name}
|
make -f Makefile.emEnv
|
||||||
|
'';
|
||||||
|
|
||||||
cp Demo* $out/share
|
outputs = [ "out" "doc" ];
|
||||||
cp -R codemirror-5.12 $out/share
|
|
||||||
cp fastXmlLint.js* $out/share
|
|
||||||
cp *.xsd $out/share
|
|
||||||
cp *.js $out/share
|
|
||||||
cp *.xhtml $out/share
|
|
||||||
cp *.html $out/share
|
|
||||||
cp *.json $out/share
|
|
||||||
cp *.rng $out/share
|
|
||||||
cp README.md $doc/share/${name}
|
|
||||||
'';
|
|
||||||
checkPhase = ''
|
|
||||||
|
|
||||||
'';
|
installPhase = ''
|
||||||
};
|
mkdir -p $out/share
|
||||||
|
mkdir -p $doc/share/${name}
|
||||||
|
|
||||||
### Declarative debugging {#declarative-debugging}
|
cp Demo* $out/share
|
||||||
|
cp -R codemirror-5.12 $out/share
|
||||||
|
cp fastXmlLint.js* $out/share
|
||||||
|
cp *.xsd $out/share
|
||||||
|
cp *.js $out/share
|
||||||
|
cp *.xhtml $out/share
|
||||||
|
cp *.html $out/share
|
||||||
|
cp *.json $out/share
|
||||||
|
cp *.rng $out/share
|
||||||
|
cp README.md $doc/share/${name}
|
||||||
|
'';
|
||||||
|
checkPhase = ''
|
||||||
|
|
||||||
|
'';
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
## Debugging {#declarative-debugging}
|
||||||
|
|
||||||
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.
|
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.
|
||||||
|
|
||||||
@ -174,9 +165,3 @@ Use `nix-shell -I nixpkgs=/some/dir/nixpkgs -A emscriptenPackages.libz` and from
|
|||||||
5. `configurePhase`
|
5. `configurePhase`
|
||||||
6. `buildPhase`
|
6. `buildPhase`
|
||||||
7. ... happy hacking...
|
7. ... happy hacking...
|
||||||
|
|
||||||
## Summary {#summary}
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
If in trouble, ask the maintainers.
|
|
||||||
|
Loading…
Reference in New Issue
Block a user