add dev helper and docs

README.md

@@ -120,6 +120,10 @@ The nix-bitcoin security fund is a 2 of 3 bitcoin multisig address open for dona
 security researchers who discover vulnerabilities in nix-bitcoin or its upstream dependencies.\
 See [Security Fund](./SECURITY.md#nix-bitcoin-security-fund) for details.
 
+Developing
+---
+See [dev/README](./dev/README.md).
+
 Troubleshooting
 ---
 If you are having problems with nix-bitcoin check the [FAQ](docs/faq.md) or submit an issue.\

dev/README.md

@@ -0,0 +1,84 @@
+This directory contains docs and helper scripts for developing and debugging:
+
+- [`dev.sh`](./dev.sh) includes misc dev helpers
+- [`dev-features.sh`](./dev-features.sh) includes helpers for developing specific
+  nix-bitcoin features (like services)
+- [`topics`](./topics) features specific topics
+
+## Setup a nix-bitcoin dev env
+
+[`create-dev-env.sh`](./create-dev-env.sh) creates a directory with the following contents:
+- The nix-bitcoin source
+- A `bin` dir for helper scripts
+- A `scenarios.nix` file for custom test scenarios
+- A `.envrc` file that defines a [direnv](https://direnv.net/) environment,
+  mainly for adding nix-bitcoin and helper scripts to `PATH`
+
+### Installation
+
+1. [Install direnv](https://direnv.net/docs/installation.html).\
+   If you use NixOS (and Bash as the default shell), just add the following to your system config:
+   ```nix
+     environment.systemPackages = [ pkgs.direnv ];
+     programs.bash.interactiveShellInit = ''
+       eval "$(direnv hook bash)"
+     '';
+   ```
+
+2. Create the dev env:
+   ```bash
+   # Set up a dev environment in dir ~/dev/nix-bitcoin
+   ./create-dev-env.sh ~/dev/nix-bitcoin
+
+   cd ~/dev/nix-bitcoin
+
+   # Enable direnv
+   direnv allow
+   ```
+
+3. Optional: Editor integration
+   - Add envrc support to your editor
+   - Setup your editor so you can easily execute lines or paragraphs from a shell script
+     file in a shell.\
+     This simplifies using dev helper scripts like [`./dev.sh`](./dev.sh).
+
+## Explore the dev env
+```bash
+cd ~/dev/nix-bitcoin
+
+ls -al . bin
+
+# You can use this file to define extra scenarios
+cat scenarios.nix
+
+# Binary `dev-run-tests` runs nix-bitcoin's `run-tests.sh` with extra scenarios from ./scenarios.nix
+# Example:
+# Run command `nodeinfo` in `myscenario` (defined in ./scenarios.nix) via a container
+dev-run-tests -s myscenario container --run c nodeinfo
+
+# Equivalent (shorthand)
+te -s myscenario container --run c nodeinfo
+
+# Run the tests for `myscenario` in a VM
+te -s myscenario
+
+# Start an interactive shell inside a VM
+te -s myscenario vm
+```
+
+See also: [examples/README.md#tests](../examples/README.md#tests)
+
+## Adding a new service
+
+It's easiest to use an existing service as a template:
+- [electrs.nix](../modules/electrs.nix): a basic service
+- [clightning.nix](../modules/clightning.nix): simple, but covers a few more features.\
+  (A `cli` binary and a runtime-composed config to include secrets.)
+- [rtl.nix](../modules/rtl.nix): includes a custom package, defined in [pkgs/rtl](../pkgs/rtl).\
+  Most other services use packages that are already included in nixpkgs.
+
+## Switching to a new NixOS release
+
+- [flake.nix](../flake.nix): update `nixpkgs.url`
+- [cirrus.yml](../.cirrus.yml): update toplevel container -> image attribute
+- [examples/configuration.nix](../examples/configuration.nix): update `system.stateVersion`

dev/create-dev-env.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# shellcheck disable=SC2016
+set -euo pipefail
+
+destdir=${1:-nix-bitcoin}
+
+mkdir -p "$destdir/bin"
+cd "$destdir"
+
+if [[ ! -e src ]]; then
+    echo "Cloning fort-nix/nix-bitcoin"
+    git clone https://github.com/fort-nix/nix-bitcoin src
+fi
+
+echo 'export root=$PWD
+export src=$root/src
+PATH_add bin
+PATH_add src/helper' > .envrc
+
+if [[ ! -e scenarios.nix ]]; then
+echo '{ pkgs, lib, scenarios, nix-bitcoin }:
+with lib;
+rec {
+
+  template = { config, pkgs, lib, ... }: {
+    imports = [
+      (nix-bitcoin + "/modules/presets/secure-node.nix")
+      scenarios.netnsBase
+      scenarios.regtestBase
+    ];
+    test.container.enableWAN = true;
+    test.container.exposeLocalhost = true;
+  };
+
+  myscenario = { config, pkgs, lib, ... }: {
+    services.clightning.enable = true;
+    nix-bitcoin.nodeinfo.enable = true;
+  };
+}' >> scenarios.nix
+fi
+
+install -m 755 <(
+    echo '#!/usr/bin/env bash'
+    echo 'exec run-tests.sh --extra-scenarios "$root/scenarios.nix" "$@"'
+) bin/dev-run-tests
+
+install -m 755 <(
+    echo '#!/usr/bin/env bash'
+    echo 'exec $src/test/run-tests.sh --out-link-prefix /tmp/nix-bitcoin/test "$@"'
+) bin/run-tests.sh
+
+ln -sfn dev-run-tests bin/te
+
+## nix-bitcoin-firejail
+
+echo 'include default.local
+include globals.local
+
+include disable-common.inc
+include disable-programs.inc
+
+caps.drop all
+netfilter
+noinput
+nonewprivs
+noroot
+notv
+novideo
+protocol unix,inet,inet6
+seccomp
+
+## Enable features
+
+allow-debuggers
+
+# Enable direnv configs
+whitelist ${HOME}/.config/direnv
+read-only ${HOME}/.config/direnv
+whitelist ${HOME}/.local/share/direnv
+read-only ${HOME}/.local/share/direnv
+whitelist ${HOME}/.cache/lorri
+read-only ${HOME}/.cache/lorri
+
+# Add your shell config files here that should be accessible in the sandbox
+whitelist ${HOME}/.bashrc
+read-only ${HOME}/.bashrc' > nix-bitcoin-firejail.conf
+
+install -m 755 <(
+    echo '#!/usr/bin/env bash'
+    echo '# A sandbox for running shells/binaries in an isolated environment'
+    echo 'exec firejail --profile="${BASH_SOURCE[0]%/*}/../nix-bitcoin-firejail.conf" "$@"'
+) bin/nix-bitcoin-firejail
+
+## git
+
+echo '/src' > .gitignore
+
+if [[ ! -e .git ]]; then
+    git init
+    git add .
+    git commit -a -m init
+fi