working-with-nix

name: working-with-nix description: Use when working with Nix flakes, selecting devShells, debugging environment issues, or understanding Nix infrastructure - covers shell selection, environment detection, common commands, and project-specific constraints like pinned Rust versions

Working with Nix in libxmtp

Quick Shell Selection

Environment Detection

echo $XMTP_NIX_ENV     # "yes" if in any Rust-based Nix shell
echo $XMTP_DEV_SHELL   # "local", "android", "ios", or unset

Critical Constraints

Rust Version is Pinned — Do Not Change

Rust 1.92.0 via flake.nix → rust-manifest. All shells use xmtp.mkToolchain. Never modify without project-wide coordination.

iOS Shell is macOS Only

The .#ios shell only works on Darwin. Requires Xcode 16+ for Swift 6.1.

Untracked Files are Invisible to Flakes

git add <new-file>  # Then rebuild — flakes only see git-tracked files

Cachix

Verify the binary cache is active: nix config show | grep substituters — should include https://xmtp.cachix.org.

Shell Architecture

Shells are independent — they compose from shared building blocks, not from each other:

shell-common.nix   → shared building blocks (rustBase, wasmEnv, tool groups)
  ├── rust.nix     → focused Rust shell (crates/bindings, lint, test)
  ├── local.nix    → full local dev (default) = all targets + debug + misc
  ├── android.nix  → Android cross-compilation
  └── ios.nix      → iOS cross-compilation (macOS only)
js.nix             → JavaScript/browser testing (no Rust)
package/wasm.nix   → WASM shell + package build

Essential Commands

# Enter shells
nix develop              # Default shell
nix develop .#rust       # Focused Rust shell
nix develop .#android    # Android shell
nix develop .#ios        # iOS shell (macOS only)
nix develop .#js         # JavaScript shell
nix develop .#wasm       # WASM shell

# Build packages
nix build .#wasm-bindings                    # WASM compiled bindings
nix build .#node-bindings-fast               # Host-matching .node binary
nix build .#node-bindings-js                 # Generated JS/TS bindings
nix build .#node-bindings-linux-x64-gnu      # Per-target .node (example)
nix build .#android-libs                     # All Android targets
nix build .#ios-libs                         # All iOS targets (macOS only)

# Explore
nix flake show           # List all outputs
nix flake metadata       # Show inputs and versions

# Debug
nix develop --show-trace  # Verbose error output

Platform Support

Key Files

Further Reference

• Shell: Default — Full local dev shell reference
• Shell: Rust — Focused Rust shell reference
• Shell: Android — Android shell reference
• Shell: iOS — iOS shell reference
• Shell: JavaScript — JavaScript shell reference
• Shell: WASM — WASM shell reference
• Nix Build Packages — All nix build .#<package> outputs
• Troubleshooting — Common issues and solutions