Building Meetily from Source

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

<details> <summary>Linux</summary>

🐧 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

bash

# 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

bash

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

Detect location: Find package.json (works from project root or frontend/)
Auto-detect GPU: Run scripts/auto-detect-gpu.js (or use TAURI_GPU_FEATURE if set)
Build Sidecar: Build llama-helper with the detected feature (debug or release)
Copy Binary: Copy the built sidecar to src-tauri/binaries with the target triple
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

bash

# 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

bash

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

bash

# 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

bash

# 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

bash

./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.)

bash

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

bash

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

bash

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

</details> <details> <summary>macOS</summary>

🍎 Building on macOS

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

1. Install Dependencies

bash

# 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

bash

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

# Production build
pnpm tauri:build

The application will be built with Metal GPU acceleration automatically.

</details> <details> <summary>Windows</summary>

🪟 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

powershell

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

</details>