Nix setup

Nix supplies the project’s pinned toolchain without requiring Docker or VS Code. A development shell makes tools available to processes on the current operating system; it is not a virtual machine. See Nix packages and shells for the individual tools provided by the flake.

Advantages and limitations

• Advantages: flake.lock pins the environment dependencies. Linux and Apple Silicon macOS users compile and run RustiQ natively with prepared Rust and optional PySCF tools. Any editor or terminal can be used.
• Platforms: this flake supports Linux x86_64 and AArch64 and Apple Silicon macOS. It does not declare native Windows or Intel macOS support.
• Windows: WSL2 adds a Linux VM and produces Linux executables. Nix inside WSL2 does not remove that virtualization layer.
• Maintenance: Nix installation, flakes, and the store introduce concepts to learn. Initial downloads or local dependency builds can take time; the store requires disk space. direnv is optional.
• HPC use: native Nix avoids a container runtime on supported hosts, but installation and access to /nix/store depend on cluster policy. Build on a suitable build node and follow the site’s scheduler and resource rules. Copying a Nix executable alone does not carry its store dependencies to another machine.

If Nix is new to you, start with the official introduction to Nix and learning resources. Nix is a package manager and development-environment tool; NixOS is a complete Linux distribution built around it. You do not need to replace your operating system with NixOS to use this repository’s flake.

Useful references include the official Nix flakes guide, nix develop reference, NixOS-WSL documentation, direnv installation guide, and nix-direnv. For tools used outside the flake, see Rustup and the uv documentation.

The flake supports the following platforms:

• Linux on x86_64 and AArch64;
• macOS on Apple Silicon.

The pinned nixpkgs revision no longer supports Intel macOS (x86_64-darwin). Use the native Cargo workflow on that platform.

On Windows, use the Linux flake through WSL2, with either NixOS-WSL or another Linux distribution with Nix installed. This builds and runs Linux executables. For a native Windows executable, use manual installation.

Getting Nix

Choose the case that matches your machine:

• On NixOS, including NixOS-WSL: Nix is already installed as part of the operating system. NixOS-WSL installation instructions are available for users who want to run NixOS directly under WSL2. Make sure the modern Nix command and flakes are enabled in your NixOS configuration:

  nix.settings.experimental-features = [ "nix-command" "flakes" ];
  

  Apply the configuration with sudo nixos-rebuild switch, then continue with nix develop or the direnv workflow below.

• On another Linux distribution, macOS, or a non-NixOS WSL2 distribution: install Nix separately as an additional package manager. It works alongside tools such as apt, dnf, pacman, or Homebrew and does not replace them. Follow the official Nix download and installation instructions for your platform, restart the shell if requested, and verify the installation with nix --version. The official page recommends a multi-user installation when the platform supports it.

In either case, Nix reads flake.nix and flake.lock from this repository to create the same project-specific toolchain without installing those development tools globally. The first invocation may take some time because Nix must download the pinned dependencies; later invocations reuse its local store.

Nix Without direnv

Install Nix with flakes enabled, clone the repository, and enter the development shell manually:

git clone https://github.com/mveril/RustiQ.git
cd RustiQ
nix develop

The default full shell provides the Rust toolchain selected by rust-toolchain.toml, the development utilities, and a Python environment built from the checked-in uv.lock. PySCF and the scientific Python dependencies are available on every platform declared by the flake. Nix places that environment directly on PATH, so no virtual environment needs to be created or activated:

python -c "import pyscf; print(pyscf.__version__)"

Platform-specific profiling and debugging tools are included where available. Run the usual Cargo commands inside the shell:

cargo build
cargo test
cargo run -- run samples/h2/sto-3g/calculation.toml

Four shells are available so that contributors only load the tools needed for their current task:

Running nix develop without a shell name selects full.

Leave the environment with exit or Ctrl-D. You can also build the default Nix package without entering the development shell:

nix build

Nix With direnv

Install both Nix and direnv, enable the direnv hook for your shell, then run:

git clone https://github.com/mveril/RustiQ.git
cd RustiQ
direnv allow

The tracked .envrc loads the full shell automatically whenever you enter the repository and unloads it when you leave. To select a lighter shell for one checkout, create an ignored .envrc.local, then allow the updated environment:

printf '%s\n' 'export RUSTIQ_DEV_SHELL=rust' > .envrc.local
direnv allow

Valid values are mini-rust, rust, mini-pyscf, and full. The tracked .envrc rejects other values before passing the selection to Nix. direnv allow is deliberately required the first time, and again after either envrc file changes, so that shell code is not executed without review. Use direnv deny to revoke permission.

Inside the Dev Container, FlakeEnv performs this integration for VS Code. The tracked .envrc remains useful for developers who use direnv in another editor or terminal.

If use flake is unknown, install or configure nix-direnv, or use nix develop directly. Some direnv/Nix installations already provide this integration.