feat(build): cuda + torch dev shell variants

[yeetypete]

NOTE: This PR is a PoC of using Nix in vision3d and may not be merged.

To test using the vision3d flake first install nix (can be done on any system): https://nixos.org/download/

What

• Provide one dev shell per (CUDA toolkit, torch) pair instead of a single hardcoded toolkit. Currently torch 2.10 on CUDA 12.8 and 2.11 through 2.13 on CUDA 13.0.
• Build the environments from uv.lock with uv2nix instead of uv sync doing it at runtime. The test suite, pyrefly, clang-tidy, the git hooks and the release artifacts become flake outputs. In CI we can just run nix build .#checks.x86_64-linux.<name>.

Why Nix

Building this project needs a CUDA toolkit, a host gcc its nvcc accepts, clang 22 for clang-tidy, and a torch built against that same toolkit. Installing these dependencies can be tricky and until now was only documented in the vision3d README. CI had to use containers (slow) to guarantee the right versions.

Reasons to move to a flake:

• Nobody has to install any development dependencies by hand anymore. The flake provides a reproducible development environment.
• A host can only have one CUDA toolkit installed at a time. vision3d can be more easily tested across different CUDA toolkit versions on a single host.
• Release wheels need the manylinux_2_28 toolchain, which used to mean building inside a specialized RHEL 8 docker image. The flake provides that toolchain as well, so nix build .#dist produces the sdist and the wheel on any host.

Testing

# Run CPU test suite, linting, git hooks on all build variants.
nix flake check
# Run CPU test suite, linting, git hooks on a single build variant.
nix build .#checks.x86_64-linux.tests-torch210-cu128
# Run a command in the dev shell for a given variant.
nix develop .#torch210-cu128 --command just test -m cpu
# Enter the development environment (torch213-cu130 default variant).
direnv allow
# Build release sdist and the manylinux_2_28 wheel. It lands in result/.
nix build .#dist

Experience with Nix

The Good:

• Full reproducibility of the dev environment and release artifacts.
• Easy to add another toolchain variant which we want to build / test vision3d against. Before each one would have required its own container and CI job.
• CI is a thin wrapper around commands anyone can run locally.
• No containers anywhere, not even for the manylinux wheel which requires a RHEL 8 toolchain / older glibc.
• Cachix makes ci significantly faster than before with containers.

The Bad:

• Most of the work is not writing Nix. It is patching software that assumes an FHS layout. CUDA, the torch wheels, manylinux and the GPU drivers all expect a system compiler and libraries in /usr/lib, and each one needs its own workaround to function outside of that.
• Debugging the toolchain is hard. Even with a good understanding of CUDA, linking and packaging debugging the build without an LLM would be tough and things that "just work" on a standard distro will not.
• The ecosystem still feels pretty young with everyone authoring and sharing various workarounds in their flakes, especially when working with CUDA. The driver discovery here is adapted from NVlabs/cutile-rs, the manylinux toolchain from huggingface/kernels, and the general community answer for drivers is a whole separate wrapper, nixGL.
• uv already provides a pretty good development environment in most cases. vision3d also uses the torch stable ABI which erases some of the benefits of needing multiple different build variants with different CUDA toolkits (they are mostly just for runtime testing).
• Nix wants to own the language package manager. This is why we use uv2nix.
• Letting uv install the environment itself is simpler, but then it is resolved at runtime and outside the store, so the reproducibility and the Cachix speedup mostly go away. The dev environment likely won't work on NixOS in that case because the wheels uv installs are prebuilt binaries linked against an FHS layout. Here we have to patch them with autoPatchelfHook to make them work.