Skip to content

CLAUDE.md

Latest commit

 

History

History
121 lines (92 loc) · 4.1 KB

CLAUDE.md

File metadata and controls

121 lines (92 loc) · 4.1 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

crate2nix generates Nix build files (Cargo.nix) for Rust/Cargo projects, enabling crate-by-crate hermetic builds with Nix. It reads Cargo.toml/Cargo.lock, resolves dependencies, prefetches hashes, and renders Nix derivations via Tera templates.

Development Environment

The project uses a Nix flake with direnv integration. Enter the dev shell via direnv allow or nix develop. All shell scripts (e.g., cargo.sh, run_tests.sh) auto-enter the pure nix-shell if not already inside.

Common Commands

Build

nix build                            # Build crate2nix via Nix
./cargo.sh build                     # Build with cargo (inside nix-shell)

Test

./run_tests.sh                       # Full test suite
./run_tests.sh --no-cargo-build      # Skip cargo build/test steps (Nix-only)
./cargo.sh test                      # Rust unit tests only
./cargo.sh test test_name            # Single Rust test
./nix-test.sh ./crate2nix/templates/nix/crate2nix/tests/default.nix
nix flake check                      # Nix integration tests

Lint & Format

./cargo.sh clippy                    # Rust linting
./cargo.sh fmt                       # Rust formatting
./nixpkgs-fmt.sh \
  ./{,nix/}{,*/}*.nix \
  ./crate2nix/templates/nix/crate2nix/{*.nix,tests/*.nix} \
  ./sample_projects/*/[[:lower:]]*.nix  # Nix formatting

Regenerate Generated Files

./regenerate_cargo_nix.sh            # Regenerate all Cargo.nix files

Docs (Astro/Starlight site in docs/)

nix build .#docs                     # Build static docs site
cd docs && npm run dev               # Local dev server
cd docs && npm run build             # Build via npm directly

Architecture

Rust Source (crate2nix/src/)

The CLI entry point is main.rs using structopt. The main command is generate.

Core pipeline in lib.rs via BuildInfo::for_config():

  1. metadata.rs - Calls cargo metadata, merges results from multiple Cargo.toml files into IndexedMetadata
  2. resolve.rs - Resolves each package into CrateDerivation with source type (CratesIo, Git, Registry, etc.), dependencies (normal/build/dev), platform conditions, and features
  3. lock.rs - Parses Cargo.lock to extract checksums, avoiding unnecessary prefetches
  4. prefetch.rs - Prefetches SHA256 hashes via nix-prefetch-url/nix-prefetch-git, caches in crate-hashes.json and registry-hashes.json
  5. render.rs - Renders output using Tera templates
  6. config.rs - Reads optional crate2nix.json for out-of-tree sources and configuration
  7. sources.rs - Manages source fetching for crates.io, git, and alternative registries

Nix Templates (crate2nix/templates/)

  • Cargo.nix.tera - Main output template; generates a Nix file that provides rootCrate, workspaceMembers, and per-crate derivations
  • nix/ - Template includes for the build infrastructure (crate building, feature resolution, etc.)

Key Nix Files (repo root)

  • tools.nix - Public Nix API; provides generatedCargoNix helper for generating Cargo.nix in Nix builds
  • tests.nix - Integration test harness; defines buildTest function and runs all sample_projects/
  • default.nix - Package derivation for crate2nix itself

Sample Projects (sample_projects/)

30+ test projects covering various scenarios: binary/library crates, features, git dependencies, workspaces, cross-compilation, cdylib, codegen, etc. Each has a pregenerated Cargo.nix that gets regenerated by regenerate_cargo_nix.sh.

Key Conventions

  • Rust edition 2021, #![forbid(unsafe_code)], #![deny(missing_docs)] in lib.rs
  • Rust formatting: edition 2018 style with reordered imports (rustfmt.toml)
  • Nix formatting: nixpkgs-fmt
  • License: Apache-2.0 (Rust crate), dual Apache-2.0/MIT (repo)
  • Version tags use bare numbers (e.g., 0.14.2, not v0.14.2)
  • The Cargo.nix files are checked into git; run_tests.sh verifies no uncommitted changes after regeneration