Platform Setup¶

Mullama builds native code via llama.cpp and supports optional audio, image, and video processing. This page covers the platform-specific dependencies you need to install.

Install Only What You Need

Not all dependencies are required. The sections below are organized by feature -- only install the packages for the features you plan to use. If you only need text generation, the essential build tools are sufficient.

Linux¶

Ubuntu / Debian¶

Essential Build Tools¶

Required for all builds:

sudo apt update
sudo apt install -y \
    build-essential \
    cmake \
    pkg-config \
    git \
    curl \
    wget

Audio Libraries¶

Required for features: multimodal, streaming-audio

sudo apt install -y \
    libasound2-dev \
    libpulse-dev \
    libflac-dev \
    libvorbis-dev \
    libopus-dev

Image Libraries¶

Required for feature: multimodal

sudo apt install -y \
    libpng-dev \
    libjpeg-dev \
    libtiff-dev \
    libwebp-dev

FFmpeg Libraries¶

Required for feature: format-conversion

sudo apt install -y \
    ffmpeg \
    libavcodec-dev \
    libavformat-dev \
    libavutil-dev \
    libswscale-dev \
    libswresample-dev

All Dependencies (One Command)¶

Install everything at once for the full feature set:

sudo apt update && sudo apt install -y \
    build-essential cmake pkg-config git curl wget \
    libasound2-dev libpulse-dev \
    libflac-dev libvorbis-dev libopus-dev \
    libpng-dev libjpeg-dev libtiff-dev libwebp-dev \
    ffmpeg libavcodec-dev libavformat-dev libavutil-dev \
    libswscale-dev libswresample-dev \
    libssl-dev

Fedora / RHEL¶

Essential Build Tools¶

sudo dnf groupinstall -y "Development Tools" "Development Libraries"
sudo dnf install -y \
    cmake \
    pkg-config \
    git \
    curl \
    wget

Audio Libraries¶

sudo dnf install -y \
    alsa-lib-devel \
    pulseaudio-libs-devel \
    flac-devel \
    libvorbis-devel \
    opus-devel

Image Libraries¶

sudo dnf install -y \
    libpng-devel \
    libjpeg-turbo-devel \
    libtiff-devel \
    libwebp-devel

FFmpeg Libraries¶

# Enable RPM Fusion for FFmpeg packages
sudo dnf install -y \
    https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm
sudo dnf install -y \
    ffmpeg-devel

All Dependencies (One Command)¶

sudo dnf install -y \
    cmake pkg-config git curl wget \
    alsa-lib-devel pulseaudio-libs-devel \
    flac-devel libvorbis-devel opus-devel \
    libpng-devel libjpeg-turbo-devel libtiff-devel libwebp-devel \
    ffmpeg-devel openssl-devel

Arch Linux¶

Essential Build Tools¶

sudo pacman -S --needed \
    base-devel \
    cmake \
    pkgconf \
    git \
    curl \
    wget

Audio Libraries¶

sudo pacman -S --needed \
    alsa-lib \
    libpulse \
    flac \
    libvorbis \
    opus

Image Libraries¶

sudo pacman -S --needed \
    libpng \
    libjpeg-turbo \
    libtiff \
    libwebp

FFmpeg Libraries¶

sudo pacman -S --needed ffmpeg

All Dependencies (One Command)¶

sudo pacman -S --needed \
    base-devel cmake pkgconf git curl wget \
    alsa-lib libpulse flac libvorbis opus \
    libpng libjpeg-turbo libtiff libwebp \
    ffmpeg openssl

macOS¶

Xcode Command Line Tools¶

Required for all builds on macOS:

xcode-select --install

Accept the License

If prompted, accept the Xcode license agreement:

sudo xcodebuild -license accept

Homebrew¶

Install the Homebrew package manager if you do not already have it:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Add Homebrew to your PATH (Apple Silicon):

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Core Build Dependencies¶

brew install cmake pkg-config

Audio Libraries¶

Required for features: multimodal, streaming-audio

macOS includes Core Audio natively. Install additional codec libraries:

brew install \
    portaudio \
    libsndfile \
    flac \
    libvorbis \
    opus

Image Libraries¶

Required for feature: multimodal

brew install \
    libpng \
    jpeg \
    libtiff \
    webp

FFmpeg¶

Required for feature: format-conversion

brew install ffmpeg

All Dependencies (One Command)¶

brew install \
    cmake pkg-config \
    portaudio libsndfile flac libvorbis opus \
    libpng jpeg libtiff webp \
    ffmpeg

Environment Configuration¶

Add to your ~/.zshrc (or ~/.bash_profile):

export PATH="/opt/homebrew/bin:$PATH"
export PKG_CONFIG_PATH="/opt/homebrew/lib/pkgconfig:$PKG_CONFIG_PATH"
export LDFLAGS="-L/opt/homebrew/lib"
export CPPFLAGS="-I/opt/homebrew/include"

Reload your shell:

source ~/.zshrc

Metal GPU Acceleration

On Apple Silicon (M1/M2/M3/M4), Metal GPU acceleration is available automatically. No additional drivers or packages are needed. See GPU Acceleration for details.

Windows¶

Visual Studio Build Tools¶

Required

A C++17 compiler is required to build the native llama.cpp code.

Visual Studio Community (Recommended)Build Tools Only (Smaller)

Download Visual Studio Community 2022 and select:

Desktop development with C++ workload
- MSVC v143 -- VS 2022 C++ x64/x86 build tools
- Windows 11 SDK (latest version)
- CMake tools for Visual Studio

Download Visual Studio Build Tools 2022 and install the C++ build tools workload.

CMake¶

CMake is included with Visual Studio. If you need a standalone installation:

# Using Chocolatey
choco install cmake -y

# Or download from https://cmake.org/download/

Core Dependencies¶

choco install git cmake ninja -y
refreshenv

Audio Dependencies¶

Windows audio APIs (WASAPI, DirectSound) are included in the Windows SDK. No additional audio packages are needed.

Windows SDK

The Windows SDK is automatically installed with the Visual Studio C++ workload. It provides all audio interfaces needed by Mullama.

Image Dependencies¶

Image processing libraries are bundled by the Rust image crate on Windows. No additional system packages are needed.

FFmpeg (Optional)¶

Required for feature: format-conversion

choco install ffmpeg -y

Or download from ffmpeg.org and add the bin directory to your system PATH.

CUDA Toolkit (Optional)¶

Required for NVIDIA GPU acceleration

Download and install the CUDA Toolkit if you have an NVIDIA GPU. See GPU Acceleration for full instructions.

Environment Variables¶

Set permanently via PowerShell (administrator):

# Ensure Ninja is used for CMake (faster builds)
[Environment]::SetEnvironmentVariable("CMAKE_GENERATOR", "Ninja", "Machine")

# For CUDA GPU acceleration (if applicable)
[Environment]::SetEnvironmentVariable("LLAMA_CUDA", "1", "Machine")

Required Submodules¶

Mullama includes llama.cpp as a git submodule. This is required for all source builds.

# If you cloned with --recurse-submodules, you are already set.
# Otherwise, initialize submodules:
git submodule update --init --recursive

Build Will Fail Without Submodules

If you see errors about missing llama.cpp source files, header files not found, or ggml.h not found, it means submodules are not initialized. Run the command above to fix this.

To update submodules to the latest upstream version:

git submodule update --remote --merge

Dependency Summary Table¶

Feature	Linux (apt)	macOS (brew)	Windows
Core (no features)	`build-essential cmake pkg-config`	`cmake pkg-config`	VS Build Tools, CMake
`multimodal` (audio)	`libasound2-dev libpulse-dev libflac-dev libvorbis-dev libopus-dev`	`portaudio libsndfile flac libvorbis opus`	Windows SDK (included)
`multimodal` (image)	`libpng-dev libjpeg-dev libtiff-dev libwebp-dev`	`libpng jpeg libtiff webp`	None (bundled)
`streaming-audio`	Same as multimodal audio	Same as multimodal audio	Same as multimodal audio
`format-conversion`	`ffmpeg libavcodec-dev libavformat-dev libavutil-dev`	`ffmpeg`	`ffmpeg` via Chocolatey
`web`, `websockets`	`libssl-dev`	Included via macOS	Included via Schannel
GPU (CUDA)	CUDA Toolkit + nvidia-driver	N/A	CUDA Toolkit
GPU (Metal)	N/A	Automatic (Apple Silicon)	N/A
GPU (ROCm)	ROCm packages	N/A	N/A

Install Rust¶

If you do not have Rust installed, use rustup:

Linux / macOSWindows

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
rustup default stable

# Using Chocolatey
choco install rustup.install -y
refreshenv
rustup default stable-x86_64-pc-windows-msvc

Or download from rustup.rs.

Verify the installation:

rustc --version   # Should be 1.75.0 or later
cargo --version
cmake --version   # Should be 3.12 or later

Common Issues and Solutions¶

pkg-config cannot find a library

Ensure the development packages are installed (the -dev or -devel suffix packages, not just the runtime libraries). On macOS, verify that PKG_CONFIG_PATH includes Homebrew:

export PKG_CONFIG_PATH="/opt/homebrew/lib/pkgconfig:$PKG_CONFIG_PATH"
pkg-config --list-all | grep pulse  # Should show libpulse

CMake version too old (Linux)

Install a newer CMake from Kitware's repository:

# Ubuntu/Debian
wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc | \
    gpg --dearmor - | sudo tee /etc/apt/trusted.gpg.d/kitware.gpg >/dev/null
sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ jammy main'
sudo apt update && sudo apt install -y cmake
cmake --version

Permission denied for audio devices (Linux)

Add your user to the audio group:

sudo usermod -a -G audio $USER

Log out and back in for the change to take effect. Verify with:

groups | grep audio

Homebrew packages not found (macOS)

Run brew doctor and ensure your shell profile exports the correct paths:

eval "$(/opt/homebrew/bin/brew shellenv)"
brew doctor

MSVC compiler not found (Windows)

Ensure the C++ build tools workload is installed in Visual Studio. Open a Developer Command Prompt or set the compiler explicitly:

$env:CC = "cl.exe"
$env:CXX = "cl.exe"

'alsa/asoundlib.h' not found

Install the ALSA development package:

# Ubuntu/Debian
sudo apt install -y libasound2-dev

# Fedora
sudo dnf install -y alsa-lib-devel

# Arch
sudo pacman -S alsa-lib

FFmpeg headers not found

Install the FFmpeg development packages (not just the ffmpeg binary):

# Ubuntu/Debian
sudo apt install -y libavcodec-dev libavformat-dev libavutil-dev

# Fedora (requires RPM Fusion)
sudo dnf install -y ffmpeg-devel

# macOS
brew install ffmpeg

OpenSSL not found (Linux)

Install the OpenSSL development package:

# Ubuntu/Debian
sudo apt install -y libssl-dev

# Fedora/RHEL
sudo dnf install -y openssl-devel

Next Steps

GPU Acceleration -- Configure CUDA, Metal, ROCm, or OpenCL
Installation -- Feature flags and build options
Your First Project -- Build a chatbot from scratch