Build Guide

October 28, 2025 ยท View on GitHub

This guide explains how to build gollama.cpp from source on different platforms.

Prerequisites

Common Requirements

  • Go 1.21 or later
  • Git
  • Make
  • CMake 3.14 or later

Platform-Specific Requirements

macOS

# Install Xcode Command Line Tools
xcode-select --install

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

# Install dependencies
brew install cmake git

Linux (Ubuntu/Debian)

# Install build tools
sudo apt-get update
sudo apt-get install -y build-essential cmake git

# For NVIDIA GPU support (optional)
# Install CUDA Toolkit from https://developer.nvidia.com/cuda-toolkit

# For AMD GPU support (optional)
# Install ROCm from https://rocm.docs.amd.com/

Linux (CentOS/RHEL/Fedora)

# CentOS/RHEL
sudo yum groupinstall "Development Tools"
sudo yum install cmake git

# Fedora
sudo dnf groupinstall "Development Tools"
sudo dnf install cmake git

Windows

# Install using Chocolatey
choco install cmake git mingw

# Or install Visual Studio 2019/2022 with C++ support
# Download from https://visualstudio.microsoft.com/

Quick Build

The fastest way to build gollama.cpp:

# Clone the repository
git clone https://github.com/dianlight/gollama.cpp
cd gollama.cpp

# Build Go bindings (libraries are downloaded automatically)
make build

# Run tests
make test

Detailed Build Process

1. Clone and Setup

git clone https://github.com/dianlight/gollama.cpp
cd gollama.cpp

# Download Go dependencies
make deps

2. Library Management

Gollama.cpp now uses pre-built binaries from official llama.cpp releases instead of local compilation.

Automatic Download

Libraries are downloaded automatically when needed:

# Build Go bindings (downloads libraries automatically if needed)
make build

# Run tests (downloads libraries automatically if needed)
make test

Manual Library Management

# Download libraries for current platform
make download-libs

# Download libraries for all platforms (for testing)
make download-libs-all

# Test library download functionality
make test-download

# Clean library cache (forces re-download)
make clean-libs

Cross-Platform Downloads

# Test downloads for all platforms
make test-download-platforms

3. Development Tools

Cross-Reference with llama.cpp Source

If you need access to llama.cpp source code and documentation for development:

# Clone llama.cpp repository for cross-reference
make clone-llamacpp

This will clone the llama.cpp repository to build/llama.cpp/ and checkout the specific version used by gollama.cpp.

4. Build Go Bindings

# Build for current platform
make build

# Build for all platforms
make build-all

# Build specific platform
GOOS=linux GOARCH=amd64 make build

5. Build Examples

make build-examples

Custom Build Configuration

Environment Variables

You can customize the build with environment variables:

# Specify llama.cpp version for downloads
export LLAMA_CPP_BUILD=b6862

# Specify Go version
export GO_VERSION=1.21

# Platform targeting
export GOOS=linux
export GOARCH=amd64

make build

Library Architecture

Gollama.cpp now uses a download-based architecture that automatically fetches pre-built binaries from the official llama.cpp releases. This eliminates the need for local compilation and complex build dependencies.

Supported Binaries

The downloader automatically selects the appropriate binary based on your platform:

  • macOS: llama-b6089-bin-macos-{arch}.zip (includes Metal support)
  • Linux: llama-b6089-bin-ubuntu-{arch}.zip (includes CUDA/HIP support)
  • Windows: llama-b6089-bin-win-cpu-{arch}.zip (CPU support, GPU support planned)

Cache Management

Downloaded libraries are cached locally to avoid repeated downloads:

# View cache location
ls ~/.cache/gollama/

# Clear cache to force re-download
make clean-libs

CPU Optimizations

# AVX support
cmake -DGGML_AVX=ON -DGGML_AVX2=ON -DGGML_AVX512=ON

# ARM NEON
cmake -DGGML_NEON=ON

# Disable optimizations for compatibility
cmake -DGGML_NATIVE=OFF

Other Options

# Build shared libraries (required for gollama.cpp)
cmake -DBUILD_SHARED_LIBS=ON

# Build tools
cmake -DBUILD_TOOLS=ON

# Enable debug info
cmake -DCMAKE_BUILD_TYPE=Debug

Cross-Compilation

Linux ARM64 from x86_64

# Install cross-compilation tools
sudo apt-get install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

# Build llama.cpp
cd build/llama.cpp
cmake -B build-linux-arm64 \
  -DCMAKE_SYSTEM_NAME=Linux \
  -DCMAKE_SYSTEM_PROCESSOR=aarch64 \
  -DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc \
  -DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++ \
  -DBUILD_SHARED_LIBS=ON
cmake --build build-linux-arm64

# Build Go bindings
GOOS=linux GOARCH=arm64 go build

Windows from Linux (MinGW)

# Install MinGW cross-compiler
sudo apt-get install mingw-w64

# Build llama.cpp
cd build/llama.cpp
cmake -B build-windows-amd64 \
  -DCMAKE_SYSTEM_NAME=Windows \
  -DCMAKE_C_COMPILER=x86_64-w64-mingw32-gcc \
  -DCMAKE_CXX_COMPILER=x86_64-w64-mingw32-g++ \
  -DBUILD_SHARED_LIBS=ON
cmake --build build-windows-amd64

# Build Go bindings
GOOS=windows GOARCH=amd64 go build

Troubleshooting

Common Issues

1. CMake Not Found

# Solution: Install CMake
# macOS: brew install cmake
# Ubuntu: sudo apt-get install cmake
# Windows: choco install cmake

2. CUDA Not Found

# Solution: Install CUDA Toolkit and set environment variables
export CUDA_PATH=/usr/local/cuda
export PATH=$CUDA_PATH/bin:$PATH
export LD_LIBRARY_PATH=$CUDA_PATH/lib64:$LD_LIBRARY_PATH

3. Metal Framework Not Found (macOS)

# Solution: Install Xcode Command Line Tools
xcode-select --install

4. Go Module Issues

# Solution: Clean and reinstall modules
go clean -modcache
go mod download
go mod tidy

5. Library Loading Issues

# Linux: Add library path
export LD_LIBRARY_PATH=$PWD/libs/linux_amd64:$LD_LIBRARY_PATH

# macOS: Add library path
export DYLD_LIBRARY_PATH=$PWD/libs/darwin_amd64:$DYLD_LIBRARY_PATH

# Windows: Add library path
set PATH=%CD%\libs\windows_amd64;%PATH%

Build Logs

Enable verbose build output for debugging:

# CMake verbose
cmake --build . --verbose

# Make verbose
make V=1

# Go verbose
go build -v

Platform-Specific Notes

macOS

  • Metal support requires macOS 10.13+ and Xcode 9+
  • Universal binaries can be built with -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64"
  • Code signing may be required for distribution

Linux

  • CUDA support requires NVIDIA driver 450+ and CUDA 11.0+
  • ROCm support requires AMD drivers and ROCm 4.0+
  • Some distributions may need additional development packages

Windows

  • Visual Studio 2019+ or MinGW-w64 is required
  • CUDA support requires Visual Studio integration
  • PATH environment variable must include library directory

Performance Optimization

Build Flags

For maximum performance:

# Go build flags
go build -ldflags="-s -w"

# CMake release build
cmake -DCMAKE_BUILD_TYPE=Release -DGGML_NATIVE=ON

CPU Architecture Specific

# For modern Intel/AMD CPUs
cmake -DGGML_AVX=ON -DGGML_AVX2=ON -DGGML_F16C=ON -DGGML_FMA=ON

# For ARM64
cmake -DGGML_NEON=ON

# For compatibility (slower but works everywhere)
cmake -DGGML_NATIVE=OFF

Contributing

When contributing builds:

  1. Test on multiple platforms if possible
  2. Document any platform-specific requirements
  3. Update this guide with new build instructions
  4. Ensure CI/CD pipeline passes

Additional Resources