Environment:Ollama Ollama CGo Runtime
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, C_CPP, Quantization |
| Last Updated | 2026-02-14 22:00 GMT |
Overview
CGo build environment with C++17 compiler toolchain, CMake, and llama.cpp dependencies required for model quantization and the native inference backend.
Description
This environment extends the Go runtime with CGo interop to the llama.cpp C++ library. The quantization pipeline (`Quantize` implementation) and native model runner both call into llama.cpp via CGo bindings. The C++ code requires a C++17-capable compiler and links against platform-specific libraries: `libstdc++` and `libm` on Linux, `lpthread` on all platforms, and Metal/Accelerate frameworks on macOS.
The build system uses CMake 3.31.2 to configure the llama.cpp C++ compilation, with `ccache` recommended for faster iterative builds. Platform-specific CGo pragmas in `.go` files define the correct include paths, compiler flags, and linker flags.
Usage
Use this environment specifically for model quantization (the `Quantize` implementation) and for building the native inference runner that executes model forward passes. If you only need to serve pre-quantized GGUF models, the GPU Runtime environment is sufficient; this environment is needed when creating quantized models from full-precision weights.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux (x86_64, arm64), macOS 14.0+, Windows | Cross-platform CGo compilation |
| C++ Compiler | GCC >= 10.2.1 (Linux x86_64) or Clang (Linux arm64, macOS) | Must support C++17 standard |
| Build Tools | CMake >= 3.31.2, ccache (recommended) | CMake configures llama.cpp build |
| Hardware | Same as Go_Runtime + GPU_Runtime | Quantization itself is CPU-bound |
Dependencies
System Packages
- `gcc` >= 10.2.1 with `g++` (Linux x86_64)
- `clang` + `clang++` (Linux arm64, macOS)
- `cmake` >= 3.31.2
- `ccache` (optional, improves rebuild times)
- `libstdc++` (Linux)
- `librt`, `libpthread`, `libdl`, `libm` (Linux)
macOS-Specific Frameworks
- `Metal` framework
- `MetalKit` framework
- `Accelerate` framework (for BLAS on Apple Silicon)
- `Foundation` framework
- `CoreGraphics` framework
Credentials
No additional credentials required beyond those in the Go_Runtime environment.
The following build-related environment variables affect compilation:
- `CGO_ENABLED`: Must be set to `1`
- `CGO_CFLAGS`: C compiler flags (recommended: `-O3`)
- `CGO_CXXFLAGS`: C++ compiler flags (recommended: `-O3`)
- `CGO_LDFLAGS`: Linker flags (macOS: `-mmacosx-version-min=14.0`)
Quick Install
# Linux (Ubuntu/Debian)
sudo apt install build-essential cmake ccache
# Linux (RHEL/Rocky)
sudo dnf install gcc-toolset-10-gcc gcc-toolset-10-gcc-c++ cmake ccache
# macOS (with Xcode Command Line Tools)
xcode-select --install
brew install cmake ccache
# Build Ollama with CGo
CGO_ENABLED=1 CGO_CFLAGS="-O3" CGO_CXXFLAGS="-O3" go build -o ollama .
Code Evidence
CGo linker directives from `ml/backend/ggml/ggml.go:3-5`:
// #cgo linux LDFLAGS: -lrt -lpthread -ldl -lstdc++ -lm
// #cgo windows LDFLAGS: -lpthread
// #cgo CPPFLAGS: -I${SRCDIR}/ggml/include
C++17 requirement from `ml/backend/ggml/ggml/src/ggml-cpu/cpu.go:3-5`:
// #cgo CFLAGS: -O3 -Wno-implicit-function-declaration
// #cgo CXXFLAGS: -std=c++17
// #cgo CPPFLAGS: -I${SRCDIR}/amx -I${SRCDIR}/llamafile
Metal framework linking from `ml/backend/ggml/ggml/src/ggml-metal/metal.go:8-9`:
// #cgo CPPFLAGS: -DGGML_METAL_NDEBUG -DGGML_METAL_EMBED_LIBRARY
// #cgo LDFLAGS: -framework Metal -framework MetalKit
macOS GPU discovery via CGo from `discover/gpu_darwin.go:4-5`:
#cgo CFLAGS: -x objective-c
#cgo LDFLAGS: -framework Foundation -framework CoreGraphics -framework Metal
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `gcc: error: unrecognized command line option '-std=c++17'` | GCC version too old | Upgrade to GCC >= 10.2.1 or use Clang |
| `ld: framework not found Metal` | Building on non-macOS or missing Xcode tools | Run `xcode-select --install` on macOS |
| `CMake Error: CMake was unable to find a build program` | CMake not installed | Install CMake >= 3.31.2 |
| `undefined reference to 'dlopen'` | Missing libdl linkage on Linux | Ensure `libdl` development package is installed |
Compatibility Notes
- Linux x86_64: Uses GCC 10.2.1+ from `gcc-toolset-10`. The C++ standard library must match the compiler version.
- Linux arm64: Uses Clang instead of GCC. Set `CC=clang CXX=clang++` in the build environment.
- macOS: Requires Xcode Command Line Tools for Metal and Accelerate framework headers. The `BF16` Metal feature flag is always enabled.
- Windows: Uses MinGW or MSVC toolchain with `lpthread` linkage.