Skip to content

BUILDING.md

Latest commit

 

History

History
319 lines (215 loc) · 8.85 KB

BUILDING.md

File metadata and controls

319 lines (215 loc) · 8.85 KB

Building Meetily from Source

This guide provides detailed instructions for building Meetily from source on different operating systems.

Linux

🐧 Building on Linux

This guide helps you build Meetily on Linux with automatic GPU acceleration. The build system detects your hardware and configures the best performance automatically.

🚀 Quick Start (Recommended for Beginners)

If you're new to building on Linux, start here. These simple commands work for most users:

1. Install Basic Dependencies

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

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

# Arch Linux
sudo pacman -S base-devel cmake git

2. Build and Run

# Development mode (with hot reload)
./dev-gpu.sh

# Production build
./build-gpu.sh

That's it! The scripts automatically detect your GPU and configure acceleration.

What Happens Automatically?

  • ✅ NVIDIA GPU → CUDA acceleration (if toolkit installed)
  • ✅ AMD GPU → ROCm acceleration (if ROCm installed)
  • ✅ No GPU → Optimized CPU mode (still works great!)

💡 Tip: If you have an NVIDIA or AMD GPU but want better performance, jump to the GPU Setup section below.

🧠 Understanding Auto-Detection

The build scripts (dev-gpu.sh and build-gpu.sh) orchestrate the entire build process. Here's how they work:

  1. Detect location: Find package.json (works from project root or frontend/)
  2. Auto-detect GPU: Run scripts/auto-detect-gpu.js (or use TAURI_GPU_FEATURE if set)
  3. Build Sidecar: Build llama-helper with the detected feature (debug or release)
  4. Copy Binary: Copy the built sidecar to src-tauri/binaries with the target triple
  5. Run Tauri: Call npm run tauri:dev or tauri:build with the feature flag passed via env var

Detection Priority

Priority Hardware What It Checks Result
1️⃣ NVIDIA CUDA nvidia-smi exists + (CUDA_PATH or nvcc found) --features cuda
2️⃣ AMD ROCm rocm-smi exists + (ROCM_PATH or hipcc found) --features hipblas
3️⃣ Vulkan vulkaninfo exists + VULKAN_SDK + BLAS_INCLUDE_DIRS set --features vulkan
4️⃣ OpenBLAS BLAS_INCLUDE_DIRS set --features openblas
5️⃣ CPU-only None of the above (no features, pure CPU)

Common Scenarios

Your System Auto-Detection Result Why
Clean Linux install CPU-only No GPU SDK detected
NVIDIA GPU + drivers only CPU-only CUDA toolkit not installed
NVIDIA GPU + CUDA toolkit CUDA acceleration ✅ Full detection successful
AMD GPU + ROCm HIPBlas acceleration ✅ Full detection successful
Vulkan drivers only CPU-only Vulkan SDK + env vars needed
Vulkan SDK configured Vulkan acceleration ✅ All requirements met

💡 Key Insight: Having GPU drivers alone isn't enough. You need the development SDK (CUDA toolkit, ROCm, or Vulkan SDK) for acceleration.

🔧 GPU Setup Guides (Intermediate)

Want better performance? Follow these guides to enable GPU acceleration.

🟢 NVIDIA CUDA Setup

Prerequisites: NVIDIA GPU with compute capability 5.0+ (check: nvidia-smi --query-gpu=compute_cap --format=csv)

Step 1: Install CUDA Toolkit
# Ubuntu/Debian (CUDA 12.x)
sudo apt install nvidia-driver-550 nvidia-cuda-toolkit

# Verify installation
nvidia-smi          # Shows GPU info
nvcc --version      # Shows CUDA version
Step 2: Build with CUDA
# Set your GPU's compute capability
# Example: RTX 3080 = 8.6 → use "86"
# Example: GTX 1080 = 6.1 → use "61"

CMAKE_CUDA_ARCHITECTURES=75 \
CMAKE_CUDA_STANDARD=17 \
CMAKE_POSITION_INDEPENDENT_CODE=ON \
./build-gpu.sh

💡 Finding Your Compute Capability:

nvidia-smi --query-gpu=compute_cap --format=csv

Convert 7.5 → 75, 8.6 → 86, etc.

Why these flags?

  • CMAKE_CUDA_ARCHITECTURES: Optimizes for your specific GPU
  • CMAKE_CUDA_STANDARD=17: Ensures C++17 compatibility
  • CMAKE_POSITION_INDEPENDENT_CODE=ON: Fixes linking issues on modern systems

🔵 Vulkan Setup (Cross-Platform Fallback)

Vulkan works on NVIDIA, AMD, and Intel GPUs. Good choice if CUDA/ROCm don't work.

Step 1: Install Vulkan SDK and BLAS
# Ubuntu/Debian
sudo apt install vulkan-sdk libopenblas-dev

# Fedora
sudo dnf install vulkan-devel openblas-devel

# Arch Linux
sudo pacman -S vulkan-devel openblas
Step 2: Configure Environment
# Add to ~/.bashrc or ~/.zshrc
export VULKAN_SDK=/usr
export BLAS_INCLUDE_DIRS=/usr/include/x86_64-linux-gnu

# Apply changes
source ~/.bashrc
Step 3: Build
./build-gpu.sh

The script will automatically detect Vulkan and build with --features vulkan.

🔴 AMD ROCm Setup (AMD GPUs Only)

Prerequisites: AMD GPU with ROCm support (RX 5000+, Radeon VII, etc.)

# Ubuntu/Debian
# Add ROCm repository (see https://rocm.docs.amd.com for latest)
sudo apt install rocm-smi hipcc

# Set environment
export ROCM_PATH=/opt/rocm

# Verify
rocm-smi            # Shows GPU info
hipcc --version     # Shows ROCm version

# Build
./build-gpu.sh

🎯 Advanced Usage

Manual Feature Override

Want to force a specific acceleration method? Use the TAURI_GPU_FEATURE environment variable with the shell scripts:

# Force CUDA (ignore auto-detection)
TAURI_GPU_FEATURE=cuda ./dev-gpu.sh
TAURI_GPU_FEATURE=cuda ./build-gpu.sh

# Force Vulkan
TAURI_GPU_FEATURE=vulkan ./dev-gpu.sh
TAURI_GPU_FEATURE=vulkan ./build-gpu.sh

# Force ROCm (HIPBlas)
TAURI_GPU_FEATURE=hipblas ./dev-gpu.sh
TAURI_GPU_FEATURE=hipblas ./build-gpu.sh

# Force CPU-only (for testing)
TAURI_GPU_FEATURE="" ./dev-gpu.sh
TAURI_GPU_FEATURE="" ./build-gpu.sh

# Force OpenBLAS (CPU-optimized)
TAURI_GPU_FEATURE=openblas ./dev-gpu.sh
TAURI_GPU_FEATURE=openblas ./build-gpu.sh

Build Output Location

After successful build:

src-tauri/target/release/bundle/appimage/Meetily_<version>_amd64.AppImage

🧭 Troubleshooting

"CUDA toolkit not found"

  • Fix: Install nvidia-cuda-toolkit or set CUDA_PATH environment variable
  • Check: nvcc --version should work

"Vulkan detected but missing dependencies"

  • Fix: Set both VULKAN_SDK and BLAS_INCLUDE_DIRS environment variables
  • Example: 
    export VULKAN_SDK=/usr
export BLAS_INCLUDE_DIRS=/usr/include/x86_64-linux-gnu

"AppImage build stripping symbols"

  • Fix: Already handled! build-gpu.sh sets NO_STRIP=true automatically
  • Why: Prevents runtime errors from missing symbols

Build works but no GPU acceleration

  • Check detection: Look at the build output for GPU detection messages
  • Verify: nvidia-smi (NVIDIA) or rocm-smi (AMD) should work
  • Missing SDK: Install the development toolkit, not just drivers
macOS

🍎 Building on macOS

On macOS, the build process is simplified as GPU acceleration (Metal) is enabled by default.

1. Install Dependencies

# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install required tools
brew install cmake node pnpm

2. Build and Run

# Development mode (with hot reload)
pnpm tauri:dev

# Production build
pnpm tauri:build

The application will be built with Metal GPU acceleration automatically.

Windows

🪟 Building on Windows

1. Install Dependencies

  • Node.js: Download and install from nodejs.org.
  • Rust: Install from rust-lang.org.
  • Visual Studio Build Tools: Install the "Desktop development with C++" workload from the Visual Studio Installer.
  • CMake: Download and install from cmake.org.

2. Build and Run

# Development mode (with hot reload)
pnpm tauri:dev

# Production build
pnpm tauri:build

By default, the application will be built with CPU-only processing. To enable GPU acceleration, see the GPU Acceleration Guide.