<div align="center">
  <img src="../assets/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
</div>

# Installation Guide

Complete setup instructions for TypeDialog development.

## Prerequisites

### Required

#### Rust & Cargo (1.70+)

Install from [https://rustup.rs/](https://rustup.rs/):

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
```text

Verify:

```bash
rustc --version
cargo --version
```text

#### just - Command Orchestration

**Option 1: Using cargo**

```bash
cargo install just
```text

**Option 2: Package manager**

```bash
# macOS
brew install just

# Debian/Ubuntu
sudo apt install just

# Arch
sudo pacman -S just

# Fedora
sudo dnf install just
```text

Verify:

```bash
just --version
```text

### Optional (for specific features)

#### Nickel CLI - For type-safe form schemas

If you plan to use Nickel (`.ncl`) form definitions:

```bash
cargo install nickel-lang
```text

Or download from: [https://github.com/nickel-lang/nickel/releases](https://github.com/nickel-lang/nickel/releases)

Verify:

```bash
nickel --version
```text

#### cargo-cross - For cross-platform compilation

For compiling to platforms other than your current OS:

```bash
cargo install cross
```text

Requires Docker to be installed.

#### cargo-watch - For development hot-reload

For automatic rebuild on file changes:

```bash
cargo install cargo-watch
```text

#### Docker - For Docker cross-compilation

For Docker-based cross-compilation (alternative to cargo-cross):

Download from: [https://www.docker.com/get-started](https://www.docker.com/get-started)

Verify:

```bash
docker --version
```text

## Installation Steps

### 1. Clone Repository

```bash
git clone https://github.com/anthropics/typedialog.git
cd typedialog
```text

### 2. Verify Dependencies

```bash
# Check all required tools
rustc --version
cargo --version
just --version

# Check optional tools (if installed)
nickel --version       # If using Nickel
cargo cross --version  # If cross-compiling
cargo watch --version  # If using watch
docker --version       # If using Docker builds
```text

### 3. Build Project

Using cargo:

```bash
cargo build
```text

Or using just:

```bash
just build::default
```text

### 4. Run Tests

```bash
# Quick test
cargo test

# Or using just
just test::all
```text

### 5. Verify Installation

```bash
# Check binaries exist
ls -la target/debug/typedialog*

# Run CLI
./target/debug/typedialog --version

# Or install
cargo install --path .
typedialog --version
```text

## Quick Verification

Run this to verify everything is working:

```bash
#!/bin/bash

echo "=== Checking Rust ==="
rustc --version || echo "❌ Rust not found"
cargo --version || echo "❌ Cargo not found"

echo "=== Checking just ==="
just --version || echo "❌ just not found"

echo "=== Optional tools ==="
nickel --version 2>/dev/null || echo "⚠ Nickel not installed (optional)"
cargo cross --version 2>/dev/null || echo "⚠ cargo-cross not installed (optional)"
cargo watch --version 2>/dev/null || echo "⚠ cargo-watch not installed (optional)"
docker --version 2>/dev/null || echo "⚠ Docker not installed (optional)"

echo "=== Building project ==="
cargo check && echo "✓ Project builds successfully" || echo "❌ Build failed"

echo "=== All checks complete ==="
```text

## Troubleshooting

### "just" command not found

Ensure `just` is installed and in PATH:

```bash
# Install
cargo install just

# Add to PATH if needed
export PATH="$HOME/.cargo/bin:$PATH"

# Verify
just --version
```text

### Rust compilation errors

Update Rust to latest stable:

```bash
rustup update
rustc --version
```text

### Permission denied on installer scripts

Make scripts executable:

```bash
chmod +x installers/bootstrap/install.sh
chmod +x scripts/*.sh
```text

### "cargo-watch not found" when using just dev::watch

Install cargo-watch:

```bash
cargo install cargo-watch
```text

### Docker not running (for cross-compilation)

Start Docker daemon:

```bash
# macOS
open -a Docker

# Linux
sudo systemctl start docker

# Verify
docker --version
```text

## Platform-Specific Setup

### macOS

```bash
# Install with Homebrew
brew install rust just

# Or manual installation
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install just
```text

### Linux (Ubuntu/Debian)

```bash
# Install from apt
sudo apt update
sudo apt install build-essential rustup just

# Or using cargo
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install just
```text

### Linux (Arch)

```bash
sudo pacman -S rust cargo just
```text

### Windows

1. Install Rust: [https://rustup.rs/](https://rustup.rs/)

1. Install just:

   ```powershell
   cargo install just
   ```

1. Or use Scoop:

   ```powershell
   scoop install just
   ```

## Next Steps

After installation:

1. **Read [development.md](development.md)** - Learn how to use just for development
2. **Check [examples/README.md](../examples/README.md)** - See working examples
3. **Read [configuration.md](configuration.md)** - Understand configuration options

## Getting Help

- Check documentation in [docs/](.)
- Review [examples/](../examples/)
- Open an issue on GitHub

---

**Installation complete!** 🎉

Next: [development.md](development.md)
