Skip to content

chore: add nix flake - #323

Open
rhousand wants to merge 1 commit into
RivoLink:mainfrom
rhousand:chore/nix-flake
Open

rhousand wants to merge 1 commit into
RivoLink:mainfrom
rhousand:chore/nix-flake

Conversation

@rhousand

@rhousand rhousand commented Oct 9, 2026

Copy link
Copy Markdown

Adds flake.nix so Nix users can build, run and install leaf from this repository, and documents Nix in the Install and Update sections of the README.

Relation to the existing PRs

Two flake PRs are already open, #286 and #118, so this one needs a reason to exist. I commented on #286 with the detail. The short version is that three things make a straightforward flake either flaky or incomplete:

  1. The test suite races under Nix. The six tests in src/tests/config.rs mutate the process-global LEAF_TAB_TITLE_LENGTH, so they race when cargo runs test threads in parallel. On an 8-core Linux builder the build fails reproducibly; on smaller runners and on Darwin it passes by luck. dontUseCargoParallelTests = true serialises the run instead of skipping tests.
  2. Two of five completions get dropped. completions/ ships bash, fish, nushell, zsh and PowerShell. All five are installed here, the ps1 by hand since installShellFiles has no PowerShell support.
  3. leaf --update cannot work from the read-only Nix store. Instead of a permission error, it now says: leaf was installed through Nix; update it with your Nix configuration instead of leaf --update

Happy for you to take whichever shape you prefer, including closing this and folding the fixes into #286.

What this gives users

nix run github:RivoLink/leaf -- README.md    # run without installing
nix profile install github:RivoLink/leaf     # install
nix develop                                  # cargo, clippy, rustfmt, rust-analyzer
nix flake check                              # build and run the full test suite

overlays.default is exported as well, so NixOS and home-manager users can add the package to their configuration.

Maintenance cost

This is meant to need no attention at release time:

  • the version is read from Cargo.toml and dependencies from Cargo.lock, so scripts/release-cut.sh needs no change and there is no hash to bump
  • completions are installed from the static files in completions/, so the built binary is never executed during the build, which also keeps cross-compilation working
  • one input, nixpkgs, and a 27-line flake.lock
  • the leaf --update rewrite uses --replace-warn, so refactoring src/main.rs degrades to the current upstream behavior locally rather than breaking nix build, while the new Nix Check workflow fails loudly if the pattern stops matching, so the rewrite cannot rot silently

The new workflow mirrors ci-check.yml in triggers, concurrency and permissions, and has a narrow paths filter so it only runs when a file that can affect the Nix build changes.

Also in flight

NixOS/nixpkgs#564648 adds leaf to nixpkgs itself as leaf-markdown-viewer. Once that lands, nix profile install nixpkgs#leaf-markdown-viewer works with no flake involved, and the README documents both. This flake covers building from source and tracking main.

Testing

  • nix build and nix flake check on aarch64-darwin: 746 tests pass, no Rust warnings and no substituteInPlace warnings
  • Nix Check green on ubuntu-latest and macos-latest: https://github.com/rhousand/leaf/actions/runs/37950254514
  • ./result/bin/leaf --version reports 1.28.3, and all five completion files are present in the output

Adds a flake so Nix users can build and run leaf from the repository,
and documents Nix in the Install and Update sections of the README.

- version and dependencies are read from Cargo.toml and Cargo.lock, so
  release-cut.sh needs no change when cutting a version
- packages.default, overlays.default, and a devShell with the toolchain
  from CONTRIBUTING.md
- the five completions in completions/ are installed from the static
  files, so the binary is never run at build time
- `leaf --update` cannot overwrite a binary in the read-only Nix store,
  so it is rewritten to point at the Nix workflow instead
- a Nix Check workflow builds and runs the test suite on ubuntu-latest
  and macos-latest, and fails if that rewrite stops matching src/main.rs
@RivoLink

Copy link
Copy Markdown
Owner

Hi @rhousand

I think this PR is more complete than the other two, but I'd prefer to wait until leaf is available on NixOS Search before merging it, so the installation instructions in the README work as expected.

Thanks again for your interest in leaf!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants