nix: fix nix build and simplify NixOS install docs

[enaples]

Important

26.06 FREEZE April 30th: Non-bugfix PRs not ready by this date will wait for 26.09.

RC1 is scheduled on May 14th

The final release is scheduled for June 1st.

Checklist

Before submitting the PR, ensure the following tasks are completed. If an item is not applicable to your PR, please mark it as checked:

• The changelog has been updated in the relevant commit(s) according to the guidelines.
• Tests have been added or modified to reflect the changes.
• Documentation has been reviewed and updated as needed.
• Related issues have been listed and linked, including any that this PR closes.
• Important All PRs must consider how to reverse any persistent changes for tools/lightning-downgrade

Rationale

CLN's ./configure detects Python through uv (see default_python in configure), which the cln derivation does not provide, so PYTHON ends up empty and the build fails when a Makefile step runs $(PYTHON) devtools/blockreplace.py. Set PYTHON=python3 in preConfigure (the derivation already ships a python3 with mako/grpcio-tools) and add blockreplace.py to patchShebangs.

With nix build working again, replace the stale poetry-based NixOS section of the install guide with the flake commands (nix build / nix run / nix profile install / nix develop).

Verified in a nixos/nix container: nix build ".?submodules=1" produces lightningd/lightning-cli v26.06.1.

Changelog-Fixed: nix: the flake build (nix build) no longer fails because ./configure cannot detect Python.

Script to test and reproduce

#!/usr/bin/env bash
# Usage:
#   ./build_cln_nixos.sh [GIT_REF] [GIT_REPO] [NIX_IMAGE] [NIX_CORES]
# Defaults:
#   GIT_REF   = test-installation-documentation-nixos
#   GIT_REPO  = https://github.com/enaples/lightning.git
#   NIX_IMAGE = nixos/nix:latest
#   NIX_CORES = 2
#
# NOTE on container mechanics (NOT part of the documented steps):
#  * The nixos/nix image cannot be driven with `docker exec` under linux/amd64
#    QEMU emulation (runc fails with "openat etc/group: path escapes from
#    parent"). So, like the Fedora/Arch scripts run one step per `docker exec`,
#    here we run one step per `docker run`. State is carried between steps by two
#    named volumes: one for the Nix store (/nix) and one for the checkout (/work).
#    The ./result symlink and its store paths both live in those volumes, so the
#    verify steps can run in their own containers.
#  * NIX_CONFIG sets `filter-syscalls = false` because Nix's seccomp BPF filter
#    cannot be loaded under QEMU emulation. NIX_PATH points <nixpkgs> at the
#    flake registry (used only to fetch git in the clone/checkout steps).
#  * NIX_CORES / CARGO_BUILD_JOBS cap parallelism: a release-profile rustc is
#    memory-hungry under emulation and OOM-kills the build (signal 9) at high
#    parallelism on a small Docker memory allotment.
# None of these are needed on a real NixOS host.

set -euo pipefail

GIT_REF="${1:-test-installation-documentation-nixos}"
GIT_REPO="${2:-https://github.com/enaples/lightning.git}"
NIX_IMAGE="${3:-nixos/nix:latest}"
NIX_CORES="${4:-2}"

NIX_VOL="cln-nixos-store"
WORK_VOL="cln-nixos-work"

# Volumes are kept between runs by default so an interrupted/OOM build can be
# resumed cheaply (compiled crates stay cached). Run with CLEAN=1 to wipe them.
CLEAN="${CLEAN:-0}"

# Run one build step in a fresh container that shares the persistent Nix store
# and work volumes.
drun() {
  docker run --rm --platform linux/amd64 \
    -v "${NIX_VOL}:/nix" \
    -v "${WORK_VOL}:/work" \
    -w /work \
    -e NIX_CONFIG=$'experimental-features = nix-command flakes\nfilter-syscalls = false' \
    -e NIX_PATH='nixpkgs=flake:nixpkgs' \
    -e CARGO_BUILD_JOBS="${NIX_CORES}" \
    "${NIX_IMAGE}" sh -c "$1"
}

cleanup() {
  echo "==> (volumes kept for resume; run CLEAN=1 ./build_cln_nixos.sh to wipe)"
}
trap cleanup EXIT

if [ "${CLEAN}" = "1" ]; then
  echo "==> CLEAN=1: removing existing volumes for a fresh build"
  docker volume rm "${NIX_VOL}" "${WORK_VOL}" >/dev/null 2>&1 || true
fi

echo "==> Cloning Core Lightning (${GIT_REPO})"
# Idempotent so the script can be re-run against kept volumes after an OOM.
drun "[ -d lightning/.git ] || nix shell nixpkgs#git --command git clone ${GIT_REPO} lightning"

echo "==> Checking out ${GIT_REF}"
drun "cd lightning && nix shell nixpkgs#git --command git fetch origin ${GIT_REF} && nix shell nixpkgs#git --command git checkout FETCH_HEAD"

echo "==> Initialising git submodules"
drun "cd lightning && nix shell nixpkgs#git --command git submodule update --init --recursive"

echo "==> Building the flake package: nix build .?submodules=1 (cores=${NIX_CORES})"
# packages.default == cln (nix/pkgs/flake-module.nix). ?submodules=1 is required
# because the build depends on git submodules. Binaries land under ./result/bin.
drun "cd lightning && nix build \".?submodules=1\" --cores ${NIX_CORES} --max-jobs 1 --print-build-logs"

echo "==> Verifying lightningd version"
drun "cd lightning && ./result/bin/lightningd --version"

echo "==> Verifying lightning-cli version"
drun "cd lightning && ./result/bin/lightning-cli --version"

echo "==> Done. NixOS flake build verified (${GIT_REPO} @ ${GIT_REF})."