Skip to content

building_in_linux.md

Latest commit

 

History

History
341 lines (236 loc) · 10.4 KB

building_in_linux.md

File metadata and controls

341 lines (236 loc) · 10.4 KB

🐧 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. They first call scripts/auto-detect-gpu.js to identify your hardware, then build the llama-helper sidecar with the appropriate features, and finally launch the Tauri application.

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

📊 Technical Reference

Complete Feature Matrix

Mode Feature Flag Requirements Acceleration Speed Boost
CUDA --features cuda nvidia-smi + (CUDA_PATH or nvcc) GPU 5-10x
ROCm --features hipblas rocm-smi + (ROCM_PATH or hipcc) GPU 4-8x
Vulkan --features vulkan vulkaninfo + VULKAN_SDK + BLAS_INCLUDE_DIRS GPU 3-6x
OpenBLAS --features openblas BLAS_INCLUDE_DIRS CPU-optimized 1.5-2x
CPU (none) (none) CPU-only 1x (baseline)

Build Scripts Internals

Both dev-gpu.sh and build-gpu.sh work the same way:

  1. Detect location: Find package.json (works from project root or frontend/)
  2. Choose package manager: Prefer pnpm, fallback to npm
  3. Call npm script: Run tauri:dev or tauri:build
  4. Auto-detect GPU: The npm script calls scripts/tauri-auto.js
  5. Feature selection: scripts/auto-detect-gpu.js checks hardware
  6. Build with features: Tauri builds with detected --features flag

Environment Variables Reference

Variable Purpose Example
CUDA_PATH CUDA installation directory /usr/local/cuda
ROCM_PATH ROCm installation directory /opt/rocm
VULKAN_SDK Vulkan SDK directory /usr
BLAS_INCLUDE_DIRS BLAS headers location /usr/include/x86_64-linux-gnu
CMAKE_CUDA_ARCHITECTURES GPU compute capability 75 (for compute 7.5)
CMAKE_CUDA_STANDARD C++ standard for CUDA 17
CMAKE_POSITION_INDEPENDENT_CODE Enable PIC for linking ON
NO_STRIP Prevent symbol stripping (AppImage) true

✅ Complete Example Builds

NVIDIA GPU (CUDA)

# Install
sudo apt install nvidia-driver-550 nvidia-cuda-toolkit

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

# Build (adjust architecture for your GPU)
CMAKE_CUDA_ARCHITECTURES=86 \ # (86 may change in your case)
CMAKE_CUDA_STANDARD=17 \
CMAKE_POSITION_INDEPENDENT_CODE=ON \
./build-gpu.sh

AMD GPU (ROCm)

# Install ROCm (see AMD docs for your distro)
sudo apt install rocm-smi hipcc
export ROCM_PATH=/opt/rocm

# Build
./build-gpu.sh

Any GPU (Vulkan)

# Install
sudo apt install vulkan-sdk libopenblas-dev

# Configure
export VULKAN_SDK=/usr
export BLAS_INCLUDE_DIRS=/usr/include/x86_64-linux-gnu

# Build
./build-gpu.sh

No GPU (CPU-only)

# Just build - works out of the box
./build-gpu.sh

Need help? Open an issue on GitHub with your GPU type, distro, and the output from ./build-gpu.sh.