cmake : introduce semantic versioning (wip) [no ci] by danbev · Pull Request #26839 · ggml-org/llama.cpp

danbev · 2026-08-10T09:32:01Z

Overview

This commit introduces semantic versioning in llama.cpp.

Additional information

This is a work in progress to figure out how this will work for llama.cpp. An example of building and installing llama.cpp to verify this can be found in examples/test-make. The README.md in that directory contains some in-progress notes.

Refs: ggml-org/ggml#1582
Refs: ggml-org/ggml#1579
Refs: make-release.yml runs on fork

Requirements

I have read and agree with the contributing guidelines
AI usage disclosure: Yes, used codex and claude.

This commit introduces semantic versioning to llama.cpp. This is a work in progress to figure out what would work.

This commit removes the nightly/release information that I added previously to keep this focused only on using building and installing llama.cpp with cmake and being able to quickly verify changes or troubleshoot issues.

This commit removes the incremental build number (versioning) support that I added. This was incorrect and we should only use the semver for the version. Releases will be tag a nightly build and package maintainers/managers that build from source can use the tag and it is therefor important that the correct version is reported. So a nightly-build will report the semver without the build number. The build number and commit as availble via cmake and test-cmake has been updated to include an example of using them: ```console $ ./build.sh [test-cmake] version: 0.1.0, build: 10360 (08c69e3) ... ``` Refs: ggml-org#26839 (comment)

danbev · 2026-08-12T07:31:59Z

I've tested this by running the following on my fork...

A simplified release.yml workflow:

workflow run
b10364 (commit: danbev@a455504)

Then manually ran the make-release.yml workflow:

workflow run
tag v0.1.0 (commit: danbev@a455504)

Note: I disabled the ggml check for the above run as it failed otherwise (correctly), as there are currently changes in the internal ggml that are not yet in upstream ggml. But the main point was to verify the nightly build check and tagging.

Refs: https://github.com/danbev/llama.cpp/actions/runs/31576801921/job/94050639145

ggerganov · 2026-08-12T09:51:56Z

Let's add a TODO to the winget workflow to update it to publish releases instead of development builds. Currently, it will pick up and submit the dev releases:

llama.cpp/.github/workflows/winget.yml

Lines 22 to 35 in 89e0aa6

    
                 - name: Find latest release 
        
                   id: find_latest_release 
        
                   uses: actions/github-script@v8 
        
                   with: 
        
                     script: | 
        
                       const { data: releases } = await github.rest.repos.listReleases({ 
        
                         owner: context.repo.owner, 
        
                         repo: context.repo.repo, 
        
                       }); 
        
                       const { tag_name: version, assets: assets } = releases.find(({assets}) => assets.find(asset => asset.name.includes('win-vulkan'))); 
        
                       const { browser_download_url: asset_url } = assets.find(asset => asset.name.includes('win-vulkan')); 
        
                       console.log("Latest release:", version); 
        
                       core.setOutput('VERSION', version); 
        
                       core.setOutput('ASSETURL', asset_url);

It's fine - we will fix it later. Just not to forget to do it.

ggerganov · 2026-08-12T10:31:34Z

Seems mergable IMO. Anything left on your end?

danbev · 2026-08-12T10:40:37Z

Seems mergable IMO. Anything left on your end?

I don't think so, I'll make the ggml PR read for review as well now.

danbev · 2026-08-12T10:42:41Z

@ggerganov What are your thoughts on handling the bumping of the versions. Should this be done per PR where it is appropriate depending on the types of changes?

ggerganov · 2026-08-12T10:50:19Z

Every PR can bump the version accordingly, but realistically we are not going to be doing that. It will be difficult for contributors who are not deeply familiar with the project to make the decisions about the version updates. And us asking them to do it on each PR will get too compicated.

The important part is when we decide to make a new release to take a look at the changes that have accumulated since the previous release, and based on that to update the llama.cpp version accordingly and put the release tag. The downstreams will eventually be building from the tagged versions, so it's not a problem if the code in-between two official versions does not have the correct LLAMA_VERSION.

CISC · 2026-08-12T11:15:44Z

Can we publish some automated Changelog somewhere? Just grab the commit titles between releases and make sure the PR links are links...

ggerganov · 2026-08-12T11:21:47Z

Can we publish some automated Changelog somewhere? Just grab the commit titles between releases and make sure the PR links are links...

I think we can simply make Github releases for the semver tags same as we do for the development releases currently in release.yml, and include the git log in the body.

ggerganov

We can do the changelog either in this PR or in a follow-up. Up to @danbev

danbev · 2026-08-12T12:08:20Z

We can do the changelog either in this PR or in a follow-up

Lets do it in a follow up if that is alright.

Signed-off-by: Gabe Goodhart <ghart@us.ibm.com> * origin/master: (383 commits) cmake : introduce semantic versioning (ggml-org#26839) gguf : harden loader against malformed tensor dims and metadata types (ggml-org#25596) kleidiai: Add runtime feature detection mechanism for aarch64/kleidiai (ggml-org#26076) model : disallow integer dflash sliding_window_pattern (ggml-org#26900) sync : ggml cmake : add config version support (ggml/1582) server : support slot save/restore with media inputs (ggml-org#26640) ui: add read_media tool (ggml-org#25877) opencl: default FA c8 cluster width to 16 on X1E (ggml-org#26433) tests : update speculative params (ggml-org#26925) vulkan: add TQ2_0 (ternary) support (ggml-org#25850) wavtokenizer-dec : bound posnet/convnext block_count against n_layer_all (ggml-org#26892) convert : handle per_layer_config in Gemma4 (transformers 5.15) (ggml-org#26882) opencl: use flat mv q5_k when weight exceeds image1d_buffer_t limit (ggml-org#26880) chat : fix muse-glimmer detection of tool calls after EOM (ggml-org#26879) ci : add missing release check (ggml-org#26923) CUDA: only disable CUDA graphs when mul_mat_id actually needs a stream sync (ggml-org#26802) cuda : add warp-per-row wkv7 kernel for single-token decode (ggml-org#26111) spec : update speculative-simple (ggml-org#26904) chat : tighten bare function parsing for Qwen models (ggml-org#26793) ...

ngxson · 2026-08-12T21:26:22Z

Thanks @danbev for taking the lead on this. I just have a deeper look on this PR and I agree to all points we have been discussing so far.

Re changelog, let's add it via a dedicated PR. Maybe we can start simple by writing a list of commits as changelog, then later on having a skills or utilize llama-server via pi agent SDK to write a better summarize for each version. TBD

ngxson · 2026-08-12T21:28:35Z

Also, for versions that require major number bump, I'd suggest assigning "breaking change" label for it. Maintainer should be responsible assigning the label ideally before merging the PR

https://github.com/ggml-org/llama.cpp/issues?q=state%3Aopen%20label%3A%22breaking%20change%22

github-actions Bot added documentation Improvements or additions to documentation build Compilation issues devops improvements to build systems and github actions mtmd Related to multimodal functionality (video/image/audio) labels Aug 10, 2026

ggerganov reviewed Aug 10, 2026

View reviewed changes

Comment thread .github/workflows/release.yml Outdated

danbev added 4 commits August 10, 2026 13:02

cmake : introduce semantic versioning (wip)

24b00db

This commit introduces semantic versioning to llama.cpp. This is a work in progress to figure out what would work.

squash! cmake : introduce semantic versioning (wip)

22443d0

cmake : update test-cmake README notes [no ci]

ca9ca71

include libmtmd in output so show its semversioned

4e3ed75

danbev force-pushed the semver branch from e65d799 to 4e3ed75 Compare August 10, 2026 11:03

danbev added 3 commits August 10, 2026 14:24

ci : add make-release workflow

afa1570

ci : fix build number check in build-cmake-pkg.yml

4bd56ae

examples : remove trailing whitespace

ffe1bce

ggerganov reviewed Aug 10, 2026

View reviewed changes

Comment thread .github/workflows/make-release.yml Outdated

ci : abort if upstream ggml version does not exist

28f8a44

ggerganov reviewed Aug 10, 2026

View reviewed changes

Comment thread .github/workflows/make-release.yml Outdated

danbev added 2 commits August 10, 2026 15:56

ci : extract step contents into scripts

d40ddf1

ci : add GGML_NATIVE=OFF to ubuntu job

1c5fe7f

ggerganov reviewed Aug 10, 2026

View reviewed changes

Comment thread examples/test-cmake/README.md Outdated

examples : remove CI build information from test-cmake [no ci]

bd4372f

This commit removes the nightly/release information that I added previously to keep this focused only on using building and installing llama.cpp with cmake and being able to quickly verify changes or troubleshoot issues.

ggerganov reviewed Aug 11, 2026

View reviewed changes

Comment thread .github/workflows/make-release.yml Outdated

danbev and others added 4 commits August 12, 2026 07:04

ci : merge scripts into single script

08c69e3

docs: add initial release.md documentation

ba7dd70

cmake : clean-up and add LLAMA_BUILD_IS_DEV option

cca739d

github-actions Bot added the testing Everything test related label Aug 12, 2026

ggerganov reviewed Aug 12, 2026

View reviewed changes

Comment thread CMakeLists.txt

ggerganov reviewed Aug 12, 2026

View reviewed changes

Comment thread .github/workflows/make-release.yml Outdated

ci : remove version input from make-release job

2697167

danbev added 2 commits August 12, 2026 10:14

ci : add LLAMA_BUILD_IS_DEV=OFF to build-cmake-pkg.yml

634fb74

Refs: https://github.com/danbev/llama.cpp/actions/runs/31576801921/job/94050639145

docs : update release notes with LLAMA_BUILD_IS_DEV info [no ci]

11de604

ci : add TODO to winget workflow [no ci]

0a3c779

danbev marked this pull request as ready for review August 12, 2026 10:39

danbev requested review from a team as code owners August 12, 2026 10:39

ggerganov approved these changes Aug 12, 2026

View reviewed changes

CISC approved these changes Aug 12, 2026

View reviewed changes

danbev merged commit 680a9ae into ggml-org:master Aug 12, 2026
1 check passed

danbev deleted the semver branch August 12, 2026 12:15

Uh oh!

Conversation

danbev commented Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Additional information

Requirements

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

danbev commented Aug 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ggerganov commented Aug 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ggerganov commented Aug 12, 2026

Uh oh!

danbev commented Aug 12, 2026

Uh oh!

danbev commented Aug 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ggerganov commented Aug 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CISC commented Aug 12, 2026

Uh oh!

ggerganov commented Aug 12, 2026

Uh oh!

ggerganov left a comment

Choose a reason for hiding this comment

Uh oh!

danbev commented Aug 12, 2026

Uh oh!

Uh oh!

ngxson commented Aug 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ngxson commented Aug 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

danbev commented Aug 10, 2026 •

edited

Loading

danbev commented Aug 12, 2026 •

edited

Loading

ggerganov commented Aug 12, 2026 •

edited

Loading

danbev commented Aug 12, 2026 •

edited

Loading

ggerganov commented Aug 12, 2026 •

edited

Loading

ngxson commented Aug 12, 2026 •

edited

Loading