From 6ecc641d087df8b8896ebd876bba592e981877c9 Mon Sep 17 00:00:00 2001 From: Jan Tojnar Date: Sat, 5 Jun 2021 21:22:45 +0200 Subject: doc: prepare for commonmark MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit We are still using Pandoc’s Markdown parser, which differs from CommonMark spec slightly. Notably: - Line breaks in lists behave differently. - Admonitions do not support the simpler syntax https://github.com/jgm/commonmark-hs/issues/75 - The auto_identifiers uses a different algorithm – I made the previous ones explicit. - Languages (classes) of code blocks cannot contain whitespace so we have to use “pycon” alias instead of Python “console” as GitHub’s linguist While at it, I also fixed the following issues: - ShellSesssion was used - Removed some pointless docbook tags. --- doc/languages-frameworks/emscripten.section.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 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 d391e038070d..b3ddf0cedaea 100644 --- a/doc/languages-frameworks/emscripten.section.md +++ b/doc/languages-frameworks/emscripten.section.md @@ -27,16 +27,14 @@ Modes of use of `emscripten`: * dev-shell for zlib implementation hacking: * `nix-shell -A emscriptenPackages.zlib` - -## Imperative usage +## Imperative usage {#imperative-usage} 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 - -## Declarative usage +## Declarative usage {#declarative-usage} Let's see two different examples from `pkgs/top-level/emscripten-packages.nix`: @@ -50,7 +48,7 @@ A special requirement of the `pkgs.buildEmscriptenPackage` is the `doCheck = tru * 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. -### Usage 1: 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 **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... @@ -110,7 +108,7 @@ See the `zlib` example: ''; }); -### Usage 2: pkgs.buildEmscriptenPackage +### Usage 2: pkgs.buildEmscriptenPackage {#usage-2-pkgs.buildemscriptenpackage} This `xmlmirror` example features a emscriptenPackage which is defined completely from this context and no `pkgs.zlib.override` is used. @@ -165,7 +163,7 @@ This `xmlmirror` example features a emscriptenPackage which is defined completel ''; }; -### Declarative debugging +### Declarative 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. @@ -177,7 +175,7 @@ Use `nix-shell -I nixpkgs=/some/dir/nixpkgs -A emscriptenPackages.libz` and from 6. `buildPhase` 7. ... happy hacking... -## Summary +## 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. -- cgit 1.4.1