From dd54e58c94943461ed0d32eff60fd52a42bf9148 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Mon, 2 Oct 2023 16:57:21 +0200 Subject: emscripten docs: reword introduction in particular, remove mention of `nix-env` Co-authored by: Henrik Karlsson --- doc/languages-frameworks/emscripten.section.md | 50 ++++++-------------------- 1 file changed, 10 insertions(+), 40 deletions(-) (limited to 'doc/languages-frameworks/emscripten.section.md') diff --git a/doc/languages-frameworks/emscripten.section.md b/doc/languages-frameworks/emscripten.section.md index 5f93dd5ff3159..d1ae7e36bf5ce 100644 --- a/doc/languages-frameworks/emscripten.section.md +++ b/doc/languages-frameworks/emscripten.section.md @@ -2,37 +2,16 @@ [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: - -* 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 "" -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} +```console +nix-shell -p emscripten +``` A few things to note: * `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} @@ -41,16 +20,13 @@ Let's see two different examples from `pkgs/top-level/emscripten-packages.nix`: * `pkgs.zlib.override` * `pkgs.buildEmscriptenPackage` -Both are interesting concepts. - -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 emscriptenPackage's `phase` to get more detailed debug output what is going wrong. -* ~/.emscripten cache is requiring us to set `HOME=$TMPDIR` in individual phases. This makes compilation slower but also makes it more deterministic. +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. -### Usage 1: pkgs.zlib.override {#usage-1-pkgs.zlib.override} +* 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. -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... See the `zlib` example: @@ -174,9 +150,3 @@ Use `nix-shell -I nixpkgs=/some/dir/nixpkgs -A emscriptenPackages.libz` and from 5. `configurePhase` 6. `buildPhase` 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. -- cgit 1.4.1