Merge pull request #258595 from fricklerhandwerk/doc-emscripten

# C compilers

/pkgs/development/compilers/gcc @amjoseph-nixpkgs

/pkgs/development/compilers/llvm @RaitoBezarius

/pkgs/development/compilers/emscripten @raitobezarius

/doc/languages-frameworks/emscripten.section.md @raitobezarius

# Audio

/nixos/modules/services/audio/botamusique.nix @mweinelt

[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 "<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}

```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}

## Examples {#declarative-usage}

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`.

This means each Emscripten package requires that a [`checkPhase`](#ssec-check-phase) is 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.

A special requirement of the `pkgs.buildEmscriptenPackage` is the `doCheck = true` is a default meaning that each emscriptenPackage requires a `checkPhase` implemented.

::: {.example #usage-1-pkgs.zlib.override}

* 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.

# Using `pkgs.zlib.override {}`

### Usage 1: pkgs.zlib.override {#usage-1-pkgs.zlib.override}

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`.

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...

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.

See the `zlib` example:

    zlib = (pkgs.zlib.override {

```nix

(pkgs.zlib.override {

  stdenv = pkgs.emscriptenStdenv;

}).overrideAttrs

(old: rec {

      --replace 'AR="libtool"' 'AR="ar"' \

      --replace 'ARFLAGS="-o"' 'ARFLAGS="-r"'

  '';

    });

})

```

### Usage 2: pkgs.buildEmscriptenPackage {#usage-2-pkgs.buildemscriptenpackage}

:::{.example #usage-2-pkgs.buildemscriptenpackage}

This `xmlmirror` example features a emscriptenPackage which is defined completely from this context and no `pkgs.zlib.override` is used.

# Using `pkgs.buildEmscriptenPackage {}`

    xmlmirror = pkgs.buildEmscriptenPackage rec {

This `xmlmirror` example features an Emscripten package that is defined completely from this context and no `pkgs.zlib.override` is used.

```nix

pkgs.buildEmscriptenPackage rec {

  name = "xmlmirror";

  buildInputs = [ pkg-config autoconf automake libtool gnumake libxml2 nodejs openjdk json_c ];

  checkPhase = ''

  '';

    };

}

```

### Declarative debugging {#declarative-debugging}

:::

## 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.

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.