CMake Presets

Using CMake presets for quick and consistent builds across platforms

Overview

CMake presets provide predefined build configurations in CMakePresets.json. They simplify building by bundling common options into named configurations.

Using Presets

Use presets with the --preset flag:

cmake --preset <preset-name>
cmake --build build-<preset-name>

The build directory name includes the preset name: build-<preset-name>

Available Presets

Linux Presets

GCC

x64-linux-gcc-debug

cmake --preset x64-linux-gcc-debug
cmake --build build-x64-linux-gcc-debug

Debug build with GCC compiler

x64-linux-gcc-release

cmake --preset x64-linux-gcc-release
cmake --build build-x64-linux-gcc-release

Release build with GCC compiler

x64-linux-gcc-reldbg

cmake --preset x64-linux-gcc-reldbg
cmake --build build-x64-linux-gcc-reldbg

Release with debug info (RelWithDebInfo)

x64-linux-gcc+static-release

cmake --preset x64-linux-gcc+static-release
cmake --build build-x64-linux-gcc+static-release

Static release build with GCC

Windows Presets

LLVM/Clang (x64)

x64-windows-llvm-debug

cmake --preset x64-windows-llvm-debug
cmake --build build-x64-windows-llvm-debug

Debug build with LLVM/Clang

x64-windows-llvm-release

cmake --preset x64-windows-llvm-release
cmake --build build-x64-windows-llvm-release

Release build with LLVM/Clang

x64-windows-llvm-reldbg

cmake --preset x64-windows-llvm-reldbg
cmake --build build-x64-windows-llvm-reldbg

Release with debug info

x64-windows-llvm+static-release

cmake --preset x64-windows-llvm+static-release
cmake --build build-x64-windows-llvm+static-release

Static release build

LLVM/Clang (ARM64)

arm64-windows-llvm-debug

cmake --preset arm64-windows-llvm-debug
cmake --build build-arm64-windows-llvm-debug

Debug build for Windows on ARM

arm64-windows-llvm-release

cmake --preset arm64-windows-llvm-release
cmake --build build-arm64-windows-llvm-release

Release build for Windows on ARM

arm64-windows-llvm+static-release

cmake --preset arm64-windows-llvm+static-release
cmake --build build-arm64-windows-llvm+static-release

Static release for Windows on ARM

MSVC

x64-windows-msvc-debug

cmake --preset x64-windows-msvc-debug
cmake --build build-x64-windows-msvc-debug

Debug build with MSVC

x64-windows-msvc-release

cmake --preset x64-windows-msvc-release
cmake --build build-x64-windows-msvc-release

Release build with MSVC (RelWithDebInfo)

x64-windows-msvc+static-release

cmake --preset x64-windows-msvc+static-release
cmake --build build-x64-windows-msvc+static-release

Static release with MSVC

SYCL (Intel GPU)

x64-windows-sycl-debug

cmake --preset x64-windows-sycl-debug
cmake --build build-x64-windows-sycl-debug

Debug build with SYCL support

x64-windows-sycl-debug-f16

cmake --preset x64-windows-sycl-debug-f16
cmake --build build-x64-windows-sycl-debug-f16

Debug build with FP16 support

x64-windows-sycl-release

cmake --preset x64-windows-sycl-release
cmake --build build-x64-windows-sycl-release

Release build with SYCL

x64-windows-sycl-release-f16

cmake --preset x64-windows-sycl-release-f16
cmake --build build-x64-windows-sycl-release-f16

Release build with FP16 support

Vulkan

x64-windows-vulkan-debug

cmake --preset x64-windows-vulkan-debug
cmake --build build-x64-windows-vulkan-debug

Debug build with Vulkan support

x64-windows-vulkan-release

cmake --preset x64-windows-vulkan-release
cmake --build build-x64-windows-vulkan-release

Release build with Vulkan support

macOS Presets

arm64-apple-clang-debug

cmake --preset arm64-apple-clang-debug
cmake --build build-arm64-apple-clang-debug

Debug build for Apple Silicon

arm64-apple-clang-release

cmake --preset arm64-apple-clang-release
cmake --build build-arm64-apple-clang-release

Release build for Apple Silicon (RelWithDebInfo)

arm64-apple-clang+static-release

cmake --preset arm64-apple-clang+static-release
cmake --build build-arm64-apple-clang+static-release

Static release for Apple Silicon

Listing Available Presets

To see all available presets:

cmake --list-presets

Example output:

Available configure presets:

  "x64-linux-gcc-debug"
  "x64-linux-gcc-release"
  "x64-linux-gcc-reldbg"
  "x64-linux-gcc+static-release"
  "arm64-windows-llvm-debug"
  "arm64-windows-llvm-release"
  ...

Preset Architecture

Base Presets

Presets inherit from hidden base configurations:

• base: Common settings for all presets

  • Generator: Ninja
  • Build directory: build-${presetName}
  • Export compile commands: ON
  • Install RPATH: $ORIGIN;$ORIGIN/..

• sycl-base: Base for SYCL builds

  • Compilers: icx (C++), cl (C)
  • SYCL enabled

Build Type Presets (Hidden)

These are combined with other presets:

• debug: CMAKE_BUILD_TYPE=Debug
• release: CMAKE_BUILD_TYPE=Release
• reldbg: CMAKE_BUILD_TYPE=RelWithDebInfo
• static: GGML_STATIC=ON

Platform Presets (Hidden)

• x64-windows-llvm: Uses x64-windows-llvm.cmake toolchain
• arm64-windows-llvm: Uses arm64-windows-llvm.cmake toolchain
• arm64-apple-clang: Uses arm64-apple-clang.cmake toolchain
• x64-linux-gcc: Uses GCC compiler

Customizing Presets

Adding CMake Options to Presets

You can add additional options when using presets:

Windows ARM with OpenMP disabled

cmake --preset arm64-windows-llvm-release -DGGML_OPENMP=OFF
cmake --build build-arm64-windows-llvm-release

Linux with CUDA

cmake --preset x64-linux-gcc-release -DGGML_CUDA=ON
cmake --build build-x64-linux-gcc-release

Creating Custom Presets

You can create a CMakeUserPresets.json file (git-ignored) for personal presets:

CMakeUserPresets.json

{
  "version": 4,
  "configurePresets": [
    {
      "name": "my-cuda-build",
      "inherits": "x64-linux-gcc-release",
      "cacheVariables": {
        "GGML_CUDA": "ON",
        "CMAKE_CUDA_ARCHITECTURES": "86"
      }
    },
    {
      "name": "my-vulkan-debug",
      "inherits": "x64-linux-gcc-debug",
      "cacheVariables": {
        "GGML_VULKAN": "ON",
        "GGML_VULKAN_VALIDATE": "ON"
      }
    }
  ]
}

Then use your custom preset:

cmake --preset my-cuda-build
cmake --build build-my-cuda-build

Preset Structure Reference

Each preset in CMakePresets.json contains:

Field	Description
name	Preset identifier
hidden	If true, preset is only for inheritance
inherits	Array of base presets to inherit from
generator	CMake generator (e.g., “Ninja”)
binaryDir	Build output directory
cacheVariables	CMake cache variables (options)
architecture	Target architecture settings
toolset	Toolset configuration

Example from CMakePresets.json:

{
  "name": "x64-windows-llvm-release",
  "inherits": [
    "base",
    "x64-windows-llvm",
    "release"
  ]
}

This preset:

1. Uses Ninja generator (from base)
2. Uses LLVM toolchain (from x64-windows-llvm)
3. Sets Release build type (from release)

Common Workflows

Development Cycle

1. Choose debug preset

   Select appropriate debug preset for your platform:

   cmake --preset x64-linux-gcc-debug
   
2. Build

   cmake --build build-x64-linux-gcc-debug
   
3. Test changes

   ./build-x64-linux-gcc-debug/bin/llama-cli -m model.gguf --version
   
4. Rebuild after changes

   CMake automatically detects changes:

   cmake --build build-x64-linux-gcc-debug
   

Release Build

1. Clean previous builds (optional)

   rm -rf build-*
   
2. Configure release preset

   cmake --preset x64-linux-gcc-release
   
3. Build with parallel jobs

   cmake --build build-x64-linux-gcc-release -j $(nproc)
   
4. Install (optional)

   cmake --install build-x64-linux-gcc-release --prefix /usr/local
   

Multi-Configuration Build

Build multiple configurations simultaneously:

# Configure all
cmake --preset x64-linux-gcc-debug
cmake --preset x64-linux-gcc-release
cmake --preset x64-linux-gcc+static-release

# Build all
cmake --build build-x64-linux-gcc-debug &
cmake --build build-x64-linux-gcc-release &
cmake --build build-x64-linux-gcc+static-release &
wait

Platform-Specific Notes

Windows

Use Developer Command Prompt for Visual Studio when using MSVC or LLVM presets.

For ARM64 builds:

cmake --preset arm64-windows-llvm-release
cmake --build build-arm64-windows-llvm-release

macOS

Apple Silicon (M1/M2/M3) builds:

cmake --preset arm64-apple-clang-release
cmake --build build-arm64-apple-clang-release

Metal is enabled by default on macOS. The preset does not disable it.

Linux

For production deployments:

cmake --preset x64-linux-gcc+static-release
cmake --build build-x64-linux-gcc+static-release

Static builds are self-contained and easier to distribute.

Troubleshooting

Preset Not Found

CMake Error: No such preset in .../CMakePresets.json: 'invalid-preset'

Solution: List available presets:

cmake --list-presets

Wrong Generator

If Ninja is not installed:

CMake Error: Could not create named generator Ninja

Solution: Install Ninja:

Debian/Ubuntu

sudo apt-get install ninja-build

Build Directory Exists

CMake Error: Build directory already configured with different preset

Solution: Remove and reconfigure:

rm -rf build-<preset-name>
cmake --preset <preset-name>

Best Practices

1. Use presets for consistency: Ensures reproducible builds across team members
2. Create user presets: Use CMakeUserPresets.json for personal configurations
3. Version control: Commit CMakePresets.json, ignore CMakeUserPresets.json
4. Name conventions: Follow existing naming patterns for clarity
5. Build isolation: Each preset uses separate build directory

Further Reading

• CMake Build Options - Detailed option reference
• Building from Source - Complete build guide
• CMake Presets Documentation - Official CMake docs