# Development Environment Setup Guide

This guide covers setting up your development environment for EVE using the automated setup scripts.

## Quick Start

### Linux/macOS

```bash
# Make script executable (if not already)
chmod +x setup.sh

# Run setup script
./setup.sh
```

### Windows

```powershell
# Run in PowerShell
.\setup.ps1
```

## What the Setup Script Does

The automated setup script will:

1. **Detect your operating system**
   - Linux (Debian/Ubuntu, Fedora/RHEL, Arch)
   - macOS
   - Windows

2. **Check for required dependencies**
   - Node.js (v18+)
   - Rust (latest stable)
   - npm or pnpm
   - Platform-specific system libraries

3. **Install missing dependencies** (with your permission)
   - Guides you through installing Node.js and Rust
   - Installs system dependencies for Tauri
   - Sets up build tools

4. **Configure your environment**
   - Creates `.env` file from template
   - Installs npm dependencies
   - Verifies installation

5. **Provide next steps**
   - Instructions for adding API keys
   - Commands to start development

## Prerequisites

### All Platforms

Before running the setup script, ensure you have:

- **Internet connection** (for downloading dependencies)
- **Administrator/sudo access** (for installing system packages)
- **~500MB free disk space** (for dependencies)

### Platform-Specific

#### Linux
- `curl` or `wget` (usually pre-installed)
- `sudo` access for installing system packages

#### macOS
- Xcode Command Line Tools (script will prompt if needed)
- Homebrew (optional, but recommended)

#### Windows
- PowerShell 5.1+ (included in Windows 10+)
- Internet Explorer or Edge (for WebView2)

## Manual Installation

If you prefer manual setup or the automated script encounters issues, follow these steps:

### 1. Install Node.js

**Linux/macOS:**
- Download from: https://nodejs.org/
- Or use nvm: https://github.com/nvm-sh/nvm

**Windows:**
- Download from: https://nodejs.org/
- Run the installer and follow prompts

Verify installation:
```bash
node -v  # Should show v18.0.0 or higher
npm -v   # Should show npm version
```

### 2. Install Rust

**All platforms:**
```bash
# Linux/macOS
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Windows (PowerShell)
# Download and run: https://win.rustup.rs/x86_64
```

Verify installation:
```bash
rustc --version
cargo --version
```

### 3. Install System Dependencies

#### Debian/Ubuntu
```bash
sudo apt update
sudo apt install libwebkit2gtk-4.0-dev \
    build-essential \
    curl \
    wget \
    file \
    libssl-dev \
    libgtk-3-dev \
    libayatana-appindicator3-dev \
    librsvg2-dev
```

#### Fedora/RHEL
```bash
sudo dnf install webkit2gtk4.0-devel \
    openssl-devel \
    curl \
    wget \
    file \
    libappindicator-gtk3-devel \
    librsvg2-devel
```

#### Arch Linux
```bash
sudo pacman -S webkit2gtk \
    base-devel \
    curl \
    wget \
    file \
    openssl \
    gtk3 \
    libappindicator-gtk3 \
    librsvg
```

#### macOS
```bash
xcode-select --install
```

#### Windows
- Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
  - Select "Desktop development with C++"
  - Select "Windows 10/11 SDK"
- Install [WebView2 Runtime](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)

### 4. Install Project Dependencies

```bash
# Clone the repository (if you haven't already)
cd eve-alpha

# Install npm dependencies
npm install

# Setup environment file
cp .env.example .env
```

### 5. Configure API Keys

Edit `.env` and add your API keys:

```env
VITE_OPENROUTER_API_KEY=sk-or-v1-your-key-here
VITE_ELEVENLABS_API_KEY=your-key-here  # Optional
```

Get your API keys:
- **OpenRouter**: https://openrouter.ai/keys (required)
- **ElevenLabs**: https://elevenlabs.io (optional, for TTS)

## Troubleshooting

### Script Fails to Detect Dependencies

If the script doesn't detect installed tools:

1. **Restart your terminal** after installing Node.js or Rust
2. **Source the cargo environment** (Linux/macOS):
   ```bash
   source $HOME/.cargo/env
   ```
3. **Add to PATH** (Windows): Ensure Node.js and Rust are in your system PATH

### Permission Denied Errors (Linux/macOS)

```bash
# Make script executable
chmod +x setup.sh

# If system package installation fails
sudo ./setup.sh  # Not recommended, use sudo only for package installs
```

### npm Install Fails

```bash
# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm cache clean --force
npm install
```

### Rust Compilation Errors (Linux)

Ensure all system dependencies are installed:
```bash
# Check webkit2gtk version
pkg-config --modversion webkit2gtk-4.0

# Should be 2.8.0 or higher
```

### Windows: "Script Cannot Be Loaded" Error

PowerShell execution policy may block the script:

```powershell
# Run as Administrator
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Then run setup script again
.\setup.ps1
```

### WebView2 Not Detected (Windows)

Download and install manually:
https://developer.microsoft.com/en-us/microsoft-edge/webview2/#download-section

## Verifying Your Setup

After running the setup script, verify everything works:

```bash
# 1. Check all tools are installed
node -v
npm -v
rustc --version
cargo --version

# 2. Start development server
npm run tauri:dev

# 3. If the app window opens and you see the chat interface, you're all set!
```

## Development Workflow

Once setup is complete:

```bash
# Start development with hot-reload
npm run tauri:dev

# Run frontend only (browser)
npm run dev

# Build for production
npm run tauri:build

# Lint code
npm run lint

# Format code
npm run format
```

## Getting Help

If you encounter issues not covered here:

1. Check the [main README](../../README.md)
2. Review [SETUP_COMPLETE.md](./SETUP_COMPLETE.md) for detailed troubleshooting
3. Check [GitHub Issues](https://github.com/your-repo/eve-alpha/issues)

## Next Steps

After successful setup:

1. ✅ Edit `.env` with your API keys
2. ✅ Run `npm run tauri:dev` to start developing
3. ✅ Read the [Development Guide](../CONTRIBUTING.md) (if available)
4. ✅ Check out the [Roadmap](../planning/ROADMAP.md) for planned features

---

**Last Updated**: October 6, 2025  
**Supported Platforms**: Linux (Debian/Ubuntu, Fedora, Arch), macOS, Windows 10/11