tombl.dev
Distro for Linux for WebAssembly
1# Contributing
2
3## Prerequisites
4
5- A Linux host with flake-enabled [Nix](https://nixos.org/download). Nix
6 bootstraps every other dependency, including the `just` command runner and
7 toolchains.
8- Clone this repository and enter `nix develop` (or
9 `echo 'use flake' > .envrc && direnv allow`, if you use direnv) to get the
10 pinned environment.
11
12## Repository layout
13
14- `packages/*/package.nix`: package definitions for wasm32-linux.
15- `overrides/*/src`: ejected sources for packages you are actively hacking on.
16- `all-packages.nix`: top-level package set wiring together the wasm packages
17 and their overrides.
18- `host-packages.nix`: mirrors the wasm packages with their nixpkgs equivalents
19 for cross-compilation.
20- `flake.nix`: entry point for developing and building with Nix flakes.
21
22## Building and running
23
24- `just run` builds and starts the system in your terminal. Run
25 `just run --help` for debug flags and host integration options.
26- `just serve` hosts the same site published at https://linux.tombl.dev so you
27 can poke it locally with browser devtools.
28- `just build <pkg>` rebuilds only the package you name after you have ejected
29 it (see below). Use this for iteration on specific components.
30
31## Working with overrides
32
33- `just eject <pkg>` copies the upstream source for that package into
34 `overrides/<pkg>/src`.
35- Once ejected, subsequent `just build <pkg>` invocations compile from the
36 override outside the Nix sandbox, so normal incremental build tools keep
37 working.
38
39## Debugging tips
40
41- Enable DWARF debugging information by setting `config.debug = true` in
42 `all-packages.nix` before rebuilding.
43- Use Chrome DevTools with the
44 [DWARF debug extension](https://goo.gle/wasm-debugging-extension)