Skip to content

BUILD_GUIDE.md

Latest commit

 

History

History
353 lines (270 loc) · 6.5 KB

BUILD_GUIDE.md

File metadata and controls

353 lines (270 loc) · 6.5 KB
Raw

DevTrack Build & Setup Guide

Quick Start

1. Backend Setup (C++23 Server)

Prerequisites

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install build-essential cmake libsqlite3-dev git

# Fedora/RHEL
sudo dnf install gcc-c++ cmake sqlite-devel git

# macOS
brew install cmake sqlite3

# Windows (with vcpkg)
vcpkg install sqlite3:x64-windows

Build Backend

cd backend

# Create build directory
mkdir -p build && cd build

# Configure with CMake
cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_STANDARD=23

# Build
cmake --build . --config Release -j$(nproc)

# Run tests (optional)
ctest --output-on-failure

# The binary will be at: build/bin/devtrack_server

Running the Backend Server

cd build/bin
./devtrack_server --port=3001 --db=~/.devtrack/devtrack.db

2. Frontend Setup (Electron + React)

Prerequisites

# Install Node.js 18+ (via nvm recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

# Or using system package manager
# Ubuntu/Debian
sudo apt-get install nodejs npm

# macOS
brew install node

Install Dependencies & Run

cd frontend

# Install dependencies
npm install
# or with pnpm (faster)
npm install -g pnpm
pnpm install

# Development mode (with hot reload)
npm run electron:dev

# Build for production
npm run electron:build

# The packaged app will be in frontend/release/

Development Workflow

Backend Development

  1. Make Changes to C++ files in backend/src/ or backend/include/

  2. Rebuild:

    cd backend/build
cmake --build . --config Release

  3. Test:

    cd backend/build
ctest --verbose

  4. Debug Build:

    cmake .. -DCMAKE_BUILD_TYPE=Debug
cmake --build .
gdb ./bin/devtrack_server

Frontend Development

  1. Run Development Server:

    cd frontend
npm run electron:dev
    • Changes to React files auto-reload
    • DevTools open by default
    • Backend must be running separately or will auto-start

  2. Code Formatting:

    npm run format

  3. Linting:

    npm run lint

Project Configuration

Backend Configuration

Create backend/config.json:

{
  "server": {
    "port": 3001,
    "host": "localhost",
    "cors": true
  },
  "database": {
    "path": "~/.devtrack/devtrack.db",
    "auto_backup": true,
    "backup_interval_hours": 24
  },
  "logging": {
    "level": "info",
    "file": "~/.devtrack/logs/devtrack.log"
  }
}

Frontend Configuration

Edit frontend/src/main/main.ts to customize:

  • Backend port
  • Window size
  • Auto-start behavior

Building for Distribution

Linux

cd frontend
npm run electron:build

# Output: frontend/release/DevTrack-1.0.0.AppImage
# or:     frontend/release/devtrack_1.0.0_amd64.deb

Windows

cd frontend
npm run electron:build

# Output: frontend/release/DevTrack Setup 1.0.0.exe

macOS

cd frontend
npm run electron:build

# Output: frontend/release/DevTrack-1.0.0.dmg

Troubleshooting

Backend Issues

Issue: CMake can't find SQLite3

# Ubuntu/Debian
sudo apt-get install libsqlite3-dev

# macOS
brew install sqlite3
export PKG_CONFIG_PATH="/usr/local/opt/sqlite/lib/pkgconfig"

# Windows
vcpkg install sqlite3:x64-windows

Issue: C++23 not supported

  • Update compiler to GCC 12+, Clang 16+, or MSVC 2022+
  • Check with: g++ --version or clang++ --version

Issue: Server won't start

# Check if port is in use
lsof -i :3001  # Unix/macOS
netstat -ano | findstr :3001  # Windows

# Check logs
tail -f ~/.devtrack/logs/devtrack.log

Frontend Issues

Issue: Electron won't start

# Clear cache
rm -rf node_modules
npm install

# Reset Electron
npm install electron --force

Issue: Can't connect to backend

  • Ensure backend is running on port 3001
  • Check frontend/src/renderer/services/api.ts for correct URL
  • Verify firewall settings

Issue: Build fails

# Clean and rebuild
rm -rf dist release
npm run build

Advanced Configuration

Using Different Databases

The backend supports custom database paths:

./devtrack_server --db=/path/to/custom.db

Custom Port Configuration

Backend:

./devtrack_server --port=8080

Frontend: Update frontend/src/main/main.ts:

const BACKEND_PORT = 8080;

Development vs Production

The app automatically detects the environment:

  • Development: Uses http://localhost:5173 for Vite dev server
  • Production: Uses bundled index.html

Performance Optimization

Backend

  • Use Release build: -DCMAKE_BUILD_TYPE=Release
  • Enable optimizations: -DCMAKE_CXX_FLAGS="-O3 -march=native"
  • Profile with perf or valgrind

Frontend

  • Lazy loading for routes
  • Code splitting with Vite
  • Minimize bundle size: 
    npm run build -- --mode production

Database Migrations

If you need to migrate data from the old C# version:

  1. Export from C# SQLite database
  2. Use the migration script (TODO: create migration script)
  3. Import into new database

Continuous Integration

Example GitHub Actions workflow:

name: Build DevTrack

on: [push, pull_request]

jobs:
  backend:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: sudo apt-get install cmake libsqlite3-dev
      - name: Build
        run: |
          cd backend
          mkdir build && cd build
          cmake .. -DCMAKE_BUILD_TYPE=Release
          cmake --build .
      - name: Test
        run: cd backend/build && ctest

  frontend:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install and build
        run: |
          cd frontend
          npm install
          npm run build

Next Steps

  1. ✅ Backend structure created
  2. ✅ Frontend structure created
  3. ⏳ Implement remaining API endpoints
  4. ⏳ Create React components
  5. ⏳ Add WebSocket support
  6. ⏳ Implement concept mapping
  7. ⏳ Add tests
  8. ⏳ Create installer packages

Resources

For more information, see the main README_NEW.md