eve-alpha/docs/setup/DEV_SETUP.md

Development Environment Setup Guide

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

Quick Start

Linux/macOS

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

# Run setup script
./setup.sh

Windows

# 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:

node -v  # Should show v18.0.0 or higher
npm -v   # Should show npm version

2. Install Rust

All platforms:

# 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:

rustc --version
cargo --version

3. Install System Dependencies

Debian/Ubuntu

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

sudo dnf install webkit2gtk4.0-devel \
    openssl-devel \
    curl \
    wget \
    file \
    libappindicator-gtk3-devel \
    librsvg2-devel

Arch Linux

sudo pacman -S webkit2gtk \
    base-devel \
    curl \
    wget \
    file \
    openssl \
    gtk3 \
    libappindicator-gtk3 \
    librsvg

macOS

xcode-select --install

Windows

• Install Visual Studio Build Tools
  • Select "Desktop development with C++"
  • Select "Windows 10/11 SDK"
• Install WebView2 Runtime

4. Install Project Dependencies

# 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:

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):

   source $HOME/.cargo/env
   

3. Add to PATH (Windows): Ensure Node.js and Rust are in your system PATH

Permission Denied Errors (Linux/macOS)

# 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

# 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:

# 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:

# 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:

# 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:

# 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
2. Review SETUP_COMPLETE.md for detailed troubleshooting
3. Check GitHub 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 (if available)
4. ✅ Check out the Roadmap for planned features

---

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