Skip to content

BUILDING.md

Latest commit

 

History

History
298 lines (235 loc) · 10.6 KB

BUILDING.md

File metadata and controls

298 lines (235 loc) · 10.6 KB
Raw

Building from source

Languages: English | 中文

This document covers how to build game_ggml_cli from source on Linux, macOS and Windows. The project is self-contained — all dependencies are pulled via CMake FetchContent at configure time.

⚠ CPU backend version/config gate — ggml v0.19.0 (temporary anchor)

The project is pinned to ggml v0.19.0; the CI CPU package is built with GGML_NATIVE=ON (captures the runner ISA). Do not bump to v0.20.x until the backend.cpp dlopen refactor is done:

  • v0.20.x turned CPU ISA variants into dlopen MODULE plugins (GGML_CPU_ALL_VARIANTS now hard-requires GGML_BACKEND_DL), and DL mode no longer links the CPU backend into the ggml umbrella target — so this project's direct ggml_backend_cpu_init / ggml_threadpool_new / ggml_backend_cpu_set_threadpool references fail to link.
  • GGML_NATIVE and GGML_BACKEND_DL are mutually exclusive upstream, so on v0.20.x you cannot keep NATIVE=ON with the dlopen path anyway.

Rationale and the full pitfall list are in AGENT.md.

Prerequisites

Linux

# Build tools
sudo apt install build-essential cmake git

# Optional: Vulkan backend (recommended for NVIDIA/AMD GPUs)
sudo apt install libvulkan-dev vulkan-tools
# glslc comes with the Vulkan SDK.  Download from LunarG:
# https://vulkan.lunarg.com/sdk/home
# Or install via package manager where available:
#   sudo apt install glslc-tools   # not available on all distros

# Optional: CUDA backend (NVIDIA GPUs)
# Install a CUDA Toolkit supported by your compiler and driver. CI uses CUDA 12.9.0.
# The prebuilt CUDA packages target Turing (CC 7.5) and newer GPUs.
# https://developer.nvidia.com/cuda-downloads

# Optional: ccache for faster rebuilds
sudo apt install ccache

macOS

# Xcode Command Line Tools
xcode-select --install

# Homebrew
brew install cmake ccache

# Metal backend is built-in — no extra SDK needed.
# For Intel Mac, cross-compile from Apple Silicon is supported:
#   cmake -DCMAKE_OSX_ARCHITECTURES=x86_64 ...

Windows

# Visual Studio 2022+ with "Desktop development with C++" workload
# Or Build Tools for Visual Studio (smaller install):
#   https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio

# CMake
#   https://cmake.org/download/ (or install via Visual Studio Installer)

# Vulkan SDK (optional, for Vulkan backend)
#   https://vulkan.lunarg.com/sdk/home
#
# CUDA Toolkit 12.9.x (optional, for CUDA backend)
#   https://developer.nvidia.com/cuda-downloads
# CUDA 12.9 supports Visual Studio 2019 16.11+ and 2022 (MSVC 192x/193x).

Windows + CUDA toolchain notes (from local builds):

  • nvcc rejects host toolchains newer than it supports. When a newer Visual Studio (e.g. VS 2026 / MSVC 19.5x) is installed it is NOT safe to assume it works with the installed CUDA — use a VS 2019 Build Tools (MSVC 14.29) and configure with the matching generator, e.g. cmake -G "Visual Studio 16 2019" -A x64 -DCMAKE_CUDA_ARCHITECTURES=75 ...
  • If several CUDA toolkits are installed, the MSBuild CUDA <ver>.targets integration picks the newest via the CUDA_PATH_V<major>_<minor> env var. Pin the one you intend to use, e.g. set CUDA_PATH_V13_0 to the v11.6 path when building with CUDA 11.6, otherwise nvcc 13 + MSVC 14.29 hits __cudaLaunch macro breakage (error C4002).
  • CI reference: ubuntu-22.04 / windows-2022 + CUDA 12.9.0.

Quick start

# Clone
git clone https://github.com/KakaruHayate/game.cpp.git
cd game.cpp

# Configure with CPU backend
cmake -B build -DCMAKE_BUILD_TYPE=Release \
               -DGAME_GGML_BUILD_CLI=ON \
               -DGAME_GGML_BUILD_TESTS=OFF

# Build
cmake --build build -j

# Verify
build/bin/game_ggml_cli --version

Backend selection

Pass one (or more) of these flags to the Configure step:

Flag Backend Default
-DGAME_GGML_METAL=ON Apple Metal (macOS only) ON on Apple
-DGAME_GGML_VULKAN=ON Vulkan (Linux/Windows) OFF
-DGAME_GGML_CUDA=ON CUDA (NVIDIA GPU) OFF

If no GPU backend is enabled, the CPU backend is used as fallback. The best available backend is selected automatically at runtime.

Examples

# Linux + Vulkan
cmake -B build -DCMAKE_BUILD_TYPE=Release \
               -DGAME_GGML_BUILD_CLI=ON \
               -DGAME_GGML_VULKAN=ON

# Linux + CUDA (requires the CUDA Toolkit and nvcc)
cmake -B build -DCMAKE_BUILD_TYPE=Release \
               -DGAME_GGML_BUILD_CLI=ON \
               -DGAME_GGML_CUDA=ON \
               -DGGML_NATIVE=OFF \
               -DCMAKE_CUDA_ARCHITECTURES="75"

# macOS Apple Silicon + Metal
cmake -B build -DCMAKE_BUILD_TYPE=Release \
               -DGAME_GGML_BUILD_CLI=ON \
               -DGAME_GGML_METAL=ON

# macOS Intel Mac (cross-compile from Apple Silicon runner)
cmake -B build -DCMAKE_BUILD_TYPE=Release \
               -DGAME_GGML_BUILD_CLI=ON \
               -DGAME_GGML_METAL=ON \
               -DCMAKE_OSX_ARCHITECTURES=x86_64

# Windows + Vulkan (from Visual Studio Developer Command Prompt / PowerShell)
cmake -B build -DCMAKE_BUILD_TYPE=Release `
               -DGAME_GGML_BUILD_CLI=ON `
               -DGAME_GGML_VULKAN=ON

# Windows + CUDA (from Visual Studio 2022 Developer PowerShell)
cmake -B build -DCMAKE_BUILD_TYPE=Release `
               -DGAME_GGML_BUILD_CLI=ON `
               -DGAME_GGML_CUDA=ON `
               -DGGML_NATIVE=OFF `
               -DCMAKE_CUDA_ARCHITECTURES="75"

Converting a PyTorch checkpoint to GGUF

The medium model checkpoint can be downloaded from OpenVPI releases.

# Install Python dependencies
pip install torch numpy gguf pyyaml

# Convert
python scripts/convert_pt_to_gguf.py \
    --model-dir GAME-1.0-medium \
    -o game_medium.gguf

# Inspect
build/bin/game_ggml_cli inspect game_medium.gguf

Expected output for the medium model:

  architecture : game-me
  embedding_dim: 256
  encoder      : 4 layers, 8 heads
  segmenter    : 8 layers, latent@6
  estimator    : 4 layers, joint attn, R=1
  tensors      : 671

Running inference

# Single file
build/bin/game_ggml_cli extract input.wav \
    -m game_medium.gguf \
    --output-formats mid \
    --output-dir out/ \
    --nsteps 8 \
    --seed 42

# Serve mode (for OpenUtau integration)
build/bin/game_ggml_cli serve game_medium.gguf
# Then write binary request frames to stdin (see src/cli/main.cpp for protocol).

# API spec: the serve protocol (VRES request frames, notes-JSON responses)
# lives in src/cli/main.cpp (`serve` command).  Packages in releases from
# v0.1.1+ speak this current protocol.
#
# > Early OpenUtau builds use the OLD API spec: install the `old_`-prefixed
# > .oudep from the v0.1.0 release (README → "OpenUtau integration"), not the
# > latest package.  Do not remove the v0.1.0 old assets — old OpenUtau needs them.

CUDA compatibility and CI scope

The hosted CI builds Linux x64 and Windows x64 CUDA packages with CUDA Toolkit 12.9.0 and Visual Studio 2022 on Windows. It verifies Toolkit discovery, CUDA compilation, linking, and packaging. On Windows, ggml-cuda.dll imports nvcuda.dll (the NVIDIA driver library) at load time, and GitHub-hosted runners have no NVIDIA driver, so the CLI cannot start there even for --version; the Windows CUDA job therefore verifies the build output and its PE import-table dependencies instead, and performs the startup smoke test only when nvcuda.dll is present (a real GPU machine). GitHub-hosted runners do not provide an NVIDIA GPU, so actual CUDA inference must still be smoke-tested on an NVIDIA system.

The release architecture list is 75;80;86;89;90;120-virtual: native SASS for Turing (CC 7.5), Ampere data-center (CC 8.0), Ampere consumer (CC 8.6), Ada (CC 8.9) and Hopper (CC 9.0), plus compute_120 PTX so RTX 50-series and future GPUs JIT with a Blackwell-targeted image. A plain 75 build also runs on newer GPUs through its bundled compute_75 PTX, but the JIT-ed kernels then miss every newer-architecture optimisation; shipping SASS for the mainstream generations removes that penalty. Compiling six architectures roughly multiplies the nvcc workload (the CUDA jobs already run with build_jobs: 2 for memory headroom), which is the trade-off for native performance on each generation.

Pascal and Volta are not included in the prebuilt package. Source builds that need these older GPUs can use CUDA 12.x and add 61-real and/or 70-real. Source builds that want to trim the list back to Turing→Ada may use 75-real;80-real;86-real;89-real, accepting the longer build and larger binary. CUDA 13.0 removed NVCC offline compilation for architectures older than CC 7.5; use CUDA 12.9 or earlier when maintaining such builds. sm_100/sm_120 (Blackwell) compile targets require CUDA 12.8 or newer.

CUDA 12.x minor-version compatibility requires at least NVIDIA driver 525.60.13 on Linux or 528.33 on Windows, subject to the limitations documented in NVIDIA's CUDA Compatibility Guide. Using the current production driver is recommended. The packages currently expect the CUDA 12 runtime and cuBLAS libraries to be installed on the target system; they do not bundle NVIDIA's runtime libraries or the driver (nvcuda.dll comes from the NVIDIA driver).

Troubleshooting

CUDA Toolkit not found

Ensure nvcc --version succeeds and that CUDA_PATH (or the platform-specific Toolkit environment) points to the intended installation. Delete build/ before reconfiguring after changing CUDA Toolkit versions.

glslc not found (Linux/Windows Vulkan)

The Vulkan SDK's glslc compiler is required by the ggml-vulkan backend. If FindVulkan reports glslc as missing, ensure the SDK is installed and its bin/ directory is on PATH:

# Linux — after installing the SDK
export VULKAN_SDK=/path/to/vulkan-sdk
export PATH="$VULKAN_SDK/bin:$PATH"

# Windows — set environment variables or pass via CMake
set VULKAN_SDK=C:\VulkanSDK\1.4.304.1
set PATH=%VULKAN_SDK%\Bin;%PATH%

unknown target CPU 'apple-m1' (macOS x86_64 cross-compile)

When cross-compiling for Intel Mac on an Apple Silicon runner, the CPU backend mistakenly detects the host as apple-m1. Disable native CPU detection:

cmake -B build -DGGML_NATIVE=OFF ...

FetchContent download failures

Dependencies are fetched via Git at configure time. If you are behind a proxy:

git config --global http.proxy http://proxy:port
git config --global https.proxy http://proxy:port

Then delete build/ and reconfigure.