nix-bitcoin/dev/README.md
2023-06-01 02:56:22 -07:00

3.5 KiB

This directory contains docs and helper scripts for developing and debugging:

See also: test/README.md

Run a dev shell

There are two ways to run a dev shell:

1. Run command nix develop

This starts a shell with test/run-tests.sh and the scripts in dir helper added to PATH.

2. Setup and start the direnv dev env

This is an opinionated, direnv-based dev env, optimized for developer experience.

dev-env/create.sh creates a git repo with the following contents:

  • Dir src which contains the nix-bitcoin repo
  • Dir bin for helper scripts
  • File scenarios.nix for custom test scenarios
  • File .envrc that defines a direnv environment, mainly for adding nix-bitcoin and helper scripts to PATH

Installation

  1. Install direnv.
    If you use NixOS (and Bash as the default shell), just add the following to your system config:

      environment.systemPackages = [ pkgs.direnv ];
      programs.bash.interactiveShellInit = ''
        eval "$(direnv hook bash)"
      '';
    
  2. Create the dev env:

    # Set up a dev environment in dir ~/dev/nix-bitcoin.
    # The dir is created automatically.
    ./dev-env/create.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.

Explore the dev env

# The direnv is automatically activated when visiting any subdir of ~/dev/nix-bitcoin
cd ~/dev/nix-bitcoin

ls -al . bin lib

# The direnv config file
cat .envrc

# 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: test/README.md

Adding a new service

It's easiest to use an existing service as a template:

  • electrs.nix: a basic service
  • clightning.nix: simple, but covers a few more features.
    (A cli binary and a runtime-composed config to include secrets.)
  • rtl.nix: includes a custom package, defined in pkgs/rtl.
    Most other services use packages that are already included in nixpkgs.

Switching to a new NixOS release