Skip to main content

​
Build Methods

Loom supports two build methods:
  1. Nix with cargo2nix (Preferred) - Reproducible builds with per-crate caching
  2. Cargo (Development) - Standard Rust toolchain builds
Nix builds are significantly faster on incremental changes due to per-crate caching. Use Cargo for quick iteration during development.

​
Nix Build (Preferred)

​
Prerequisites

1

Install Nix

Install Nix with flakes enabled:
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
2

Enable Flakes

Flakes should be enabled by default with the Determinate Systems installer. Verify:
nix --version

​
Building Loom

Loom uses cargo2nix for reproducible builds with per-crate caching: 
# Build the CLI
nix build .#loom-cli-c2n

# Binary available at:
./result/bin/loom --version

​
cargo2nix Workflow

When you modify Cargo.toml or Cargo.lock:
1

Update Cargo.lock

cargo update
2

Regenerate Cargo.nix

cargo2nix-update
This regenerates Cargo.nix with the updated dependency graph.
3

Commit Both Files

git add Cargo.lock Cargo.nix
git commit -m "Update dependencies"
cargo2nix doesn’t track include_str! file changes. If you add/modify migration files or other embedded resources, run cargo2nix-update to force a rebuild by changing the hash.

​
Cargo Build (Development)

​
Prerequisites

1

Install Rust

Install Rust using rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
2

Verify Installation

rustc --version
cargo --version

​
Building with Cargo

# Build everything in the workspace
cargo build --workspace

# Release build
cargo build --workspace --release

​
Full Check

Run all quality checks: 
make check
This runs:
  1. cargo fmt --all -- --check - Format verification
  2. cargo clippy --workspace -- -D warnings - Linting
  3. cargo build --workspace - Build
  4. cargo test --workspace - Tests

​
Build Profiles

Loom uses optimized build profiles:

​
Development Profile

Cargo.toml
[profile.dev]
debug = 1                    # Reduced debug info
split-debuginfo = "unpacked" # Faster linking
incremental = true           # Enable incremental compilation

​
Fast Profile

For git hooks and quick iteration: 
cargo build --profile dev-fast
Cargo.toml
[profile.dev-fast]
inherits = "dev"
debug = 0                    # No debug info
codegen-units = 512          # Maximum parallelism

​
Release Profile

Cargo.toml
[profile.release]
lto = false                  # No link-time optimization
opt-level = 0                # No optimization for fastest compile
codegen-units = 256          # High parallelism
strip = "debuginfo"          # Strip debug symbols
Loom’s release profile prioritizes fast compilation over runtime performance since deployment uses Nix builds.

​
Installation Locations

​
System-wide Installation

Add to your ~/.config/nixpkgs/config.nix or NixOS configuration:
{
  environment.systemPackages = [
    (import /path/to/loom).packages.x86_64-linux.loom-cli-c2n
  ];
}

​
Development Installation

For development, use the binary directly: 
# Cargo build
./target/release/loom --version

# Nix build
./result/bin/loom --version

​
Web Frontend

The web UI is built with SvelteKit:
1

Install pnpm

curl -fsSL https://get.pnpm.io/install.sh | sh -
2

Install Dependencies

cd web/loom-web
pnpm install
3

Run Development Server

pnpm dev
Open http://localhost:5173
4

Build for Production

pnpm build

​
Server Deployment

Loom server runs on NixOS with auto-update:

​
NixOS Auto-Update

Deployments happen automatically on git push to trunk: 
git push origin trunk
The production server:
  1. Checks for new commits every 10 seconds
  2. Rebuilds using Nix when changes detected
  3. Restarts the loom-server systemd service

​
Verify Deployment

1

Check Deployed Revision

sudo cat /var/lib/nixos-auto-update/deployed-revision
2

Check Service Status

sudo systemctl status nixos-auto-update.service
sudo systemctl status loom-server
3

View Update Logs

sudo journalctl -u nixos-auto-update.service -f
4

Verify Health Endpoint

curl -s https://loom.ghuntley.com/health | jq .

​
Force Rebuild

If auto-update is stuck: 
sudo rm /var/lib/nixos-auto-update/deployed-revision
sudo systemctl start nixos-auto-update.service

​
Database Migrations

All migrations live in crates/loom-server/migrations/:

​
Adding Migrations

1

Create Migration File

# Find next available number
ls crates/loom-server/migrations/

# Create new migration (e.g., 025_new_feature.sql)
touch crates/loom-server/migrations/025_new_feature.sql
2

Write SQL

crates/loom-server/migrations/025_new_feature.sql
-- Add your migration SQL
CREATE TABLE IF NOT EXISTS new_table (
  id TEXT PRIMARY KEY,
  created_at INTEGER NOT NULL
);
3

Force Rebuild

Critical: cargo2nix doesn’t track include_str! changes. You must regenerate Cargo.nix:
cargo2nix-update
git add Cargo.nix crates/loom-server/migrations/025_new_feature.sql
git commit -m "Add new feature migration"
Without this, the deployed binary won’t include the new migration!

​
Migration Testing

Test migrations locally: 
LOOM_SERVER_DB_PATH=/tmp/test.db ./target/release/loom-server
Migrations run automatically on server startup.

​
Troubleshooting

​
Nix Build Fails

# Clear nix cache
nix-collect-garbage

# Rebuild
nix build .#loom-cli-c2n --rebuild

​
Cargo Build Fails

# Clean build artifacts
cargo clean

# Update dependencies
cargo update

# Rebuild
cargo build --workspace

​
cargo2nix Out of Sync

If Nix build fails with dependency errors: 
# Ensure Cargo.lock is up to date
cargo update

# Regenerate Cargo.nix
cargo2nix-update

# Try build again
nix build .#loom-cli-c2n

​
Next Steps

Quick Start

Start your first REPL session

Configuration

Configure Loom for your environment

Development Guide

Learn about code style, testing, and contributing

Deployment

Deploy Loom server to production

Build docs developers (and LLMs) love

Get started for freeTalk to us