GGML Synchronization and Contributing

Relevant source files

• AUTHORS
• LICENSE
• ggml/cmake/GitVars.cmake
• ggml/cmake/ggml-config.cmake.in
• scripts/gen-authors.sh
• scripts/sync-ggml-am.sh
• scripts/sync-ggml.last
• scripts/sync-ggml.sh

Purpose and Scope

This document covers the synchronization process between the GGML tensor library and llama.cpp, including the tools and workflows used to keep GGML code up-to-date within the llama.cpp repository. It also provides guidelines for contributors working with GGML-related code.

For information about the GGML library architecture itself, see GGML Core Architecture. For details on building and testing, see Build System and Configuration and Testing Infrastructure.

Repository Structure and Relationship

llama.cpp embeds GGML as an integrated subtree rather than using a git submodule. The GGML code resides in the ggml/ directory within llama.cpp and is periodically synchronized from the upstream GGML repository.

Directory Mapping

Directory Structure Overview

GGML Source Path	llama.cpp Target Path	Content
CMakeLists.txt	ggml/CMakeLists.txt	Main build configuration
src/CMakeLists.txt	ggml/src/CMakeLists.txt	Source build configuration
cmake/*	ggml/cmake/*	CMake modules and utilities
src/ggml*	ggml/src/ggml*	Core GGML implementation
include/ggml*.h	ggml/include/ggml*.h	Public GGML headers
tests/test-opt.cpp	tests/test-opt.cpp	Optimization tests
tests/test-backend-ops.cpp	tests/test-backend-ops.cpp	Backend operation tests
LICENSE	LICENSE	MIT License

Sources: scripts/sync-ggml.sh1-21 scripts/sync-ggml-am.sh1-159

Synchronization Tracking

Last Synchronized Commit

The file scripts/sync-ggml.last tracks the most recent GGML commit that has been synchronized into llama.cpp. This file contains a single commit hash.

Current tracked commit: scripts/sync-ggml.last1

d6754f3d0e6d0acd21c12442353c9fd2f94188e7

This hash serves as the baseline for incremental synchronization using the patch-based approach.

Sources: scripts/sync-ggml.last1-2

Synchronization Methods

llama.cpp provides two distinct synchronization scripts with different use cases and workflows.

Method 1: Direct Copy Synchronization

Script: sync-ggml.sh

This is the simpler synchronization method that directly copies files from the upstream GGML repository.

Usage:

Process:

1. Assumes GGML repository is located at ../ggml
2. Copies files directly using cp -rpv (recursive, preserve attributes, verbose)
3. No git history integration
4. Manual commit required after sync

Files synchronized: scripts/sync-ggml.sh3-20

• CMakeLists.txt → ggml/CMakeLists.txt
• src/CMakeLists.txt → ggml/src/CMakeLists.txt
• cmake/* → ggml/cmake/*
• src/ggml-cpu/cmake/* → ggml/src/ggml-cpu/cmake/*
• src/ggml* → ggml/src/
• include/ggml*.h → ggml/include/
• include/gguf*.h → ggml/include/
• Test files
• LICENSE and scripts/gen-authors.sh

Sources: scripts/sync-ggml.sh1-21

Method 2: Git Patch-Based Synchronization

Script: sync-ggml-am.sh

This is the sophisticated synchronization method that applies GGML commits as git patches, preserving commit history and authorship.

Usage:

Command-line Options: scripts/sync-ggml-am.sh28-44

• -skip hash0,hash1,... - Skip specific commit hashes during sync
• -C N - Set git patch context to N lines (default: 8)

Process Flow:

1. Read baseline: Load last synced commit from sync-ggml.last scripts/sync-ggml-am.sh24
2. Generate commit list: git log --oneline $lc..HEAD scripts/sync-ggml-am.sh48
3. Filter commits: Exclude commits already merged (containing (llama/[0-9]*)) scripts/sync-ggml-am.sh49
4. Create patches: For each commit, generate unified diff with context scripts/sync-ggml-am.sh69-86
5. Transform PR references: Convert (#1234) to (ggml/1234) scripts/sync-ggml-am.sh99-107
6. Remap paths: Transform GGML paths to llama.cpp structure scripts/sync-ggml-am.sh130-145
7. Apply patches: git am -C${ctx} ggml-src.patch scripts/sync-ggml-am.sh147
8. Update tracking: Write new HEAD hash to sync-ggml.last scripts/sync-ggml-am.sh154

Sources: scripts/sync-ggml-am.sh1-159

Path Transformation Rules

The sync script applies extensive path transformations to map GGML paths to llama.cpp structure:

Pattern	Transformation	Example
CMakeLists.txt	ggml/CMakeLists.txt	Root build file
src/CMakeLists.txt	ggml/src/CMakeLists.txt	Source build file
cmake/*.cmake	ggml/cmake/*.cmake	CMake modules
src/ggml*	ggml/src/ggml*	Core sources
include/ggml*.h	ggml/include/ggml*.h	Public headers
include/gguf*.h	ggml/include/gguf*.h	GGUF headers
tests/*.cpp	tests/*.cpp	Test files (no prefix)

Sources: scripts/sync-ggml-am.sh130-145

Synchronized File Inventory

Sources: scripts/sync-ggml-am.sh69-86

Contributing Guidelines

Making GGML Changes

For changes that affect only GGML:

1. Submit changes to the upstream GGML repository first
2. Wait for merge and CI validation in GGML
3. Synchronize changes to llama.cpp using sync scripts
4. Submit PR to llama.cpp with synchronized changes

For changes that affect both GGML and llama.cpp:

1. Coordinate with both project maintainers
2. Consider whether the change belongs in GGML core or llama.cpp
3. Submit to appropriate repository first based on dependency

Commit Message Conventions

When synchronizing GGML commits, PR references are automatically transformed:

Original:  some text (#1234)
Transform: some text (ggml/1234)

This transformation is applied to both commit subjects and message bodies scripts/sync-ggml-am.sh99-107

Skipping Problematic Commits

If certain commits cause conflicts or should not be synchronized:

The script will skip these hashes during patch generation scripts/sync-ggml-am.sh34-37

Adjusting Patch Context

For complex merges, increase git patch context:

Default context is 8 lines scripts/sync-ggml-am.sh30

Sources: scripts/sync-ggml-am.sh28-44 scripts/sync-ggml-am.sh99-107

For CI/CD pipeline details including sanitizer jobs and backend test matrix, see page 9.3.

Authorship and Attribution

Author Tracking

The AUTHORS file tracks all contributors to both GGML and llama.cpp repositories.

Generation Script: scripts/gen-authors.sh1-10

The script:

1. Extracts author name and email from all commits
2. Removes duplicates while preserving first occurrence order
3. Sorts alphabetically
4. Updates timestamp header

Current authors: Over 1,400 contributors as of AUTHORS1

Sources: scripts/gen-authors.sh1-10 AUTHORS1-6

Git Variable Extraction

ggml/cmake/GitVars.cmake is part of the synchronized CMake module set. It runs git at configure time to embed version metadata into the build.

Diagram: GitVars.cmake Variable Extraction

Sources: ggml/cmake/GitVars.cmake1-23

CMake Package Configuration

Find Dependencies in Consumer Projects

When llama.cpp is installed and used as a library, the GGML CMake configuration handles dependency discovery:

Configuration Template: ggml/cmake/ggml-config.cmake.in1-192

The generated ggml-config.cmake file is installed alongside the GGML libraries and consumed by downstream CMake projects via find_package(ggml). Key behaviors:

1. Dependency resolution — Automatically invokes find_dependency for required libraries (Threads, OpenMP, BLAS, CUDAToolkit, Metal frameworks, OpenCL, Vulkan, HIP, SYCL/oneMKL) only when GGML_SHARED_LIB is OFF (static linking) ggml/cmake/ggml-config.cmake.in8-98
2. Path validation — Uses set_and_check to verify GGML_INCLUDE_DIR and GGML_LIB_DIR are present at install time ggml/cmake/ggml-config.cmake.in100-102
3. Backend enumeration — Iterates GGML_AVAILABLE_BACKENDS to create one imported target per backend ggml/cmake/ggml-config.cmake.in129-177
4. CPU backend detection — Matches ^ggml-cpu via regex to apply CPU-specific link libraries and options separately from GPU backends ggml/cmake/ggml-config.cmake.in149-173

Imported CMake Targets

Target	Type	Notes
ggml::ggml	UNKNOWN IMPORTED	Main ggml library; links all backends via INTERFACE_LINK_LIBRARIES
ggml::ggml-base	UNKNOWN IMPORTED	Base support library, linked by all backends
ggml::<backend>	UNKNOWN IMPORTED	One per entry in GGML_AVAILABLE_BACKENDS (e.g. ggml::ggml-cuda)
ggml::all	INTERFACE IMPORTED	Convenience target linking all backend targets

Backend Target Creation: ggml/cmake/ggml-config.cmake.in129-188

The following diagram maps the CMake variables and targets defined in ggml-config.cmake.in:

Diagram: ggml-config.cmake.in Target Graph

Sources: ggml/cmake/ggml-config.cmake.in1-192

Troubleshooting Synchronization

Common Issues

Issue: Patch application fails

error: patch failed: ggml/src/ggml.c:1234
error: ggml/src/ggml.c: patch does not apply

Solution: Increase context lines:

Issue: Conflicting commits

Some commits may have already been applied or conflict with llama.cpp-specific changes.

Solution: Skip problematic commits:

Issue: PR number collision

GGML PR #123 and llama.cpp PR #123 are different PRs.

Solution: The sync script automatically transforms references to (ggml/123) scripts/sync-ggml-am.sh103

Manual Sync Recovery

If automatic sync fails and creates a bad state:

1. Reset to last known good state:

2. Check sync baseline:

3. Resume from specific commit:

4. Verify synchronized files:

Sources: scripts/sync-ggml-am.sh147-155