Installation¶

This page covers every step required to build and test ZigLlama on a fresh machine. By the end you will have a working checkout with all 285+ tests passing.

Prerequisites¶

Zig 0.13+¶

ZigLlama targets Zig 0.13.0 or later. Zig is distributed as a single static binary -- no installer, no system packages, no dependency chains.

# Download the latest 0.13.x release
curl -LO https://ziglang.org/download/0.13.0/zig-linux-x86_64-0.13.0.tar.xz
tar xf zig-linux-x86_64-0.13.0.tar.xz

# Move to a permanent location
sudo mv zig-linux-x86_64-0.13.0 /opt/zig

# Add to PATH (append to ~/.bashrc or ~/.zshrc)
export PATH="/opt/zig:$PATH"

# Via Homebrew (recommended)
brew install zig

# Or download manually
curl -LO https://ziglang.org/download/0.13.0/zig-macos-aarch64-0.13.0.tar.xz
tar xf zig-macos-aarch64-0.13.0.tar.xz
sudo mv zig-macos-aarch64-0.13.0 /opt/zig
export PATH="/opt/zig:$PATH"

# Via Scoop
scoop install zig

# Or download the zip from https://ziglang.org/download/
# Extract and add the directory to your system PATH.

Verify the installation:

zig version
# Expected output: 0.13.0 (or later)

Hardware Requirements¶

Optional Tools¶

Clone the Repository¶

git clone https://github.com/dipankar/zigllama.git
cd zigllama

The checkout is self-contained. There are no Git submodules, no vendored C libraries, and no code-generation steps.

Verify the Installation¶

Run the full test suite to confirm everything works:

zig build test

You can also run tests for individual layers to isolate any problems:

# Foundation layer only (tensors, memory management)
zig build test-foundation

# Linear algebra layer only (SIMD ops, quantisation)
zig build test-linear-algebra

If all tests pass, your installation is complete. Jump to the Quick Start to run your first inference demo.

Optional: BLAS Libraries¶

ZigLlama includes a pure-Zig matrix multiplication kernel that works everywhere. For maximum throughput on large models, you can optionally link against an optimised BLAS library.

OpenBLAS¶

sudo apt install libopenblas-dev

sudo dnf install openblas-devel

brew install openblas
export LIBRARY_PATH="/opt/homebrew/opt/openblas/lib:$LIBRARY_PATH"

Intel MKL¶

Intel oneAPI Math Kernel Library provides the fastest BLAS on Intel CPUs.

# Install via the Intel package repository (Debian/Ubuntu)
wget -O- https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB \
  | gpg --dearmor | sudo tee /usr/share/keyrings/oneapi-archive-keyring.gpg > /dev/null

echo "deb [signed-by=/usr/share/keyrings/oneapi-archive-keyring.gpg] \
  https://apt.repos.intel.com/oneapi all main" \
  | sudo tee /etc/apt/sources.list.d/oneAPI.list

sudo apt update && sudo apt install intel-oneapi-mkl-devel
source /opt/intel/oneapi/setvars.sh

Apple Accelerate¶

On macOS, the Accelerate framework is pre-installed. No additional configuration is needed; ZigLlama's BLAS integration layer detects it automatically at build time.

# Verify Accelerate is available
xcrun --show-sdk-path
# Should print something like /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk

Platform Support Matrix¶

zig build -Dtarget=aarch64-linux-gnu

Troubleshooting¶

error: expected expression or parser failures¶

Cause: Zig version too old.

Fix: Upgrade to Zig 0.13.0 or later. Check with zig version.

error: FileNotFound when running tests¶

Cause: Working directory is not the repository root.

Fix: Make sure you cd zigllama before running zig build test.

BLAS not detected at build time¶

Cause: The BLAS shared library is not on the default library search path.

Fix: Set LIBRARY_PATH (compile time) and LD_LIBRARY_PATH (run time) to the directory containing libopenblas.so or libmkl_rt.so.

export LIBRARY_PATH=/opt/openblas/lib:$LIBRARY_PATH
export LD_LIBRARY_PATH=/opt/openblas/lib:$LD_LIBRARY_PATH

Out-of-memory during large model loading¶

Cause: The model file exceeds available RAM.

Fix: Use a quantised model (Q4_K or smaller) or enable memory mapping. ZigLlama's GGUF loader uses mmap by default on Linux and macOS, so the operating system can page in only the portions of the model file that are actively needed.

Slow SIMD performance¶

Cause: The CPU does not support AVX2, or the build was compiled in Debug mode.

Fix: Verify CPU support with:

# Linux
grep -o 'avx2' /proc/cpuinfo | head -1

# macOS
sysctl -a | grep machdep.cpu.features | grep AVX2

If AVX2 is available, rebuild in ReleaseFast mode:

zig build test -Doptimize=ReleaseFast

See Building from Source for guidance on build modes.

Tests pass but examples fail to run¶

Cause: Examples are standalone Zig files that import from src/. They must be run from the repository root.

Fix:

cd /path/to/zigllama
zig run examples/simple_demo.zig

Next Steps¶

• Quick Start Guide -- run your first inference.
• Building from Source -- customise the build for your platform.
• Project Structure -- understand the codebase layout.