feat(nix): ❄️ add a flake with package, app and dev shell

[Panadestein]

🤖 AI text below 🤖

Adds a Nix flake so Nix/NixOS users can build and hack on monoprop without installing the C++ toolchain, hwloc, Boost or MPI by hand.

Stacked on #314 — this branch is rebased onto chore-mpi4py-build-req-dynamically and should merge after it.

Outputs

Command	What it gives you
nix develop	dev shell: GCC 15, CMake, Ninja, Boost, hwloc, Open MPI, uv, just, Node.js, clang-tools, gdb, lcov, doxygen
nix build .#monoprop	the Python package, without MPI
nix build .#monoprop-mpi	the same package with monoprop_ENABLE_MPI=ON
nix run	a Python interpreter with monoprop importable

Inside nix develop, the existing uv sync and just workflows apply unchanged. The shell sets UV_PYTHON_PREFERENCE=only-system (uv's managed interpreters expect a loader NixOS does not provide, and [tool.uv] pins only-managed) and LD_LIBRARY_PATH so manylinux wheels resolve libstdc++.

Blocker: the packages do not currently build

nix build .#monoprop and .#monoprop-mpi both fail in pypaBuildPhase with Unmet dependencies: #243 pinned nanobind==3.0.0 and added nanobind-backend>=1.0.0 to [build-system] requires, but nixpkgs ships nanobind 2.13.0 and has no nanobind-backend at all. This predates the rebase — it arrived in this branch through its last Merge branch 'main' and the validation below was never re-run against it. The flake needs the same kind of override it already applies to scikit-build-core before this can merge. The dev shell is unaffected.

Deviations from the uv build

All in nix/monoprop.nix and documented in the building guide:

• C++ unit tests are off — they resolve msgpack-cxx through a CPM git fetch that the build sandbox denies. Build them from the dev shell instead.
• monoprop_ENABLE_ARCH_FLAGS is off, since a store path may be substituted onto a machine other than the one that built it. .override { enableArchFlags = true; } restores -march=native.
• The version is pinned, because setuptools-scm cannot read git metadata inside the sandbox. It needs bumping alongside the release tag.
• MPI is enabled by setting the CMake option directly rather than through build(python): 🎨 dynamically add mpi4py to build-system.requires #314's monoprop_ENABLE_MPI environment switch, because that switch also appends mpi4py to build.requires — a PyPI resolution the sandbox denies. The store copy of mpi4py is supplied as a build input of monoprop-mpi only.

Notes for reviewers

• nixpkgs ships scikit-build-core 1.0.2 while [build-system] requires asks for >=1.0.3, so the flake overrides it with the 1.0.3 PyPI sdist. That override should be dropped once nixpkgs catches up.
• tools/generate-dispatch.py reads .github/license-header.txt during cmake --install, but .github is in sdist.exclude. The flake works around it by including that one file in the source set; an sdist-based install would presumably hit the same failure.

Validation

On x86_64-linux, before #243 landed: nix build .#monoprop and .#monoprop-mpi both compiled and passed the import check, nix flake check passed, nix run evaluated a MajoranaOperator, and uv sync inside nix develop built the bindings against the Nix toolchain. All of that needs re-running once the nanobind override is in. Darwin and aarch64-linux are exposed via flake-utils.lib.eachDefaultSystem but untested.

[github-actions]

Docs preview: https://pr-241.monoprop-docs.pages.dev

[Panadestein]

Why not uv2nix?

I evaluated uv2nix for this flake and decided against it. uv2nix turns uv.lock into the nix dependency graph, so nix and uv can't drift. That's valuable when the lock file describes the hard part of your build, but here it doesn't:

• uv doesn't lock build backends (astral-sh/uv#5190). uv.lock contains no nanobind, scikit-build-core or setuptools-scm, so the entire C++ build (toolchain, boost/hwloc/MPI, the nanobind CMake dir, the arch-flag and unit-test toggles) would still be handwritten
• The runtime closure is trivial: numpy and msgpack, both in nixpkgs at the locked versions. No dependency problem to solve.
• It would degrade the dev shell. uv sync inside nix develop gives an incremental C++ build tree; a nix-built venv replaces fast ninja rebuilds with a full derivation rebuild per edit.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.70%. Comparing base (236d4fb) to head (40de449).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #241   +/-   ##
=======================================
  Coverage   97.70%   97.70%           
=======================================
  Files          14       14           
  Lines         742      742           
  Branches       98       98           
=======================================
  Hits          725      725           
  Misses         12       12           
  Partials        5        5           

Flag	Coverage Δ
cpp	97.70% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

[robertodr]

LGTM, thank you @Panadestein.

[robertodr]

as a follow-up, we can simplify a lot once these two PRs to nixpkgs land:

• python3Packages.nanobind: 2.13.0 -> 3.0.1 NixOS/nixpkgs#558385
• nanobind-backend: init at 1.0.0 NixOS/nixpkgs#558388
  and when the scikit-build-core derivation gets updated.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Panadestein]

Thanks for the improvements @robertodr !