* cmake : introduce semantic versioning (wip)
This commit introduces semantic versioning to llama.cpp.
* squash! cmake : introduce semantic versioning (wip)
* cmake : update test-cmake README notes [no ci]
* include libmtmd in output so show its semversioned
* ci : add make-release workflow
* ci : fix build number check in build-cmake-pkg.yml
* examples : remove trailing whitespace
* ci : abort if upstream ggml version does not exist
* ci : extract step contents into scripts
* ci : add GGML_NATIVE=OFF to ubuntu job
* examples : remove CI build information from test-cmake [no ci]
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.
* ci : merge scripts into single script
* remove -dev-build_number support
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 (
08c69e381)
...
```
Refs: https://github.com/ggml-org/llama.cpp/pull/26839#discussion_r3755836969
* docs: add initial release.md documentation
* cmake : clean-up and add LLAMA_BUILD_IS_DEV option
* ci : remove version input from make-release job
* ci : add LLAMA_BUILD_IS_DEV=OFF to build-cmake-pkg.yml
Refs: https://github.com/danbev/llama.cpp/actions/runs/
31576801921/job/
94050639145
* docs : update release notes with LLAMA_BUILD_IS_DEV info [no ci]
* ci : add TODO to winget workflow [no ci]
---------
Co-authored-by: Georgi Gerganov <redacted>
-DLLAMA_BUILD_TOOLS=OFF \
-DLLAMA_BUILD_EXAMPLES=OFF \
-DLLAMA_BUILD_APP=OFF \
+ -DLLAMA_BUILD_IS_DEV=OFF \
-DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release
cmake --install build --prefix "$PREFIX" --config Release
tclsh <<'EOF'
set build(commit) [string trim [exec git rev-parse --short HEAD]]
set build(number) [string trim [exec git rev-list --count HEAD]]
- set build(version) "0.0.$build(number)"
+
+ set cmakelists [read [open "CMakeLists.txt" r]]
+ regexp {set\(LLAMA_VERSION_MAJOR\s+(\d+)\)} $cmakelists -> major
+ regexp {set\(LLAMA_VERSION_MINOR\s+(\d+)\)} $cmakelists -> minor
+ regexp {set\(LLAMA_VERSION_PATCH\s+(\d+)\)} $cmakelists -> patch
+ set build(version) "$major.$minor.$patch"
set llamaconfig [read [open "$env(LLAMA_CONFIG)" r]]
set checks [list "set\\(LLAMA_VERSION \\s+$build(version)\\)" \
run: |
cmake -B build \
-DLLAMA_FATAL_WARNINGS=ON \
- -DGGML_RPC=ON
+ -DGGML_RPC=ON \
+ -DGGML_NATIVE=OFF
time cmake --build build --config Release -j $(nproc)
- name: Test
--- /dev/null
+name: Make Release
+
+on:
+ workflow_dispatch:
+ inputs:
+ dry_run:
+ description: 'Dry run - validate without creating the tag'
+ required: true
+ type: boolean
+ default: true
+
+env:
+ GH_TOKEN: ${{ github.token }}
+
+permissions:
+ contents: write
+
+jobs:
+ make-release:
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v6
+
+ - name: Run release checks
+ id: checks
+ run: bash scripts/make-release-checks.sh ${{ github.event.inputs.dry_run == 'true' && '--dry-run' || '' }}
+ env:
+ GITHUB_REPOSITORY: ${{ github.repository }}
+
+ - name: Create release tag
+ if: ${{ github.event.inputs.dry_run == 'false' }}
+ run: |
+ VERSION="${{ steps.checks.outputs.version }}"
+ git config user.name "github-actions[bot]"
+ git config user.email "github-actions[bot]@users.noreply.github.com"
+ git tag -a "${VERSION}" -m "Release ${VERSION}"
+ git push origin "${VERSION}"
+ echo "Created and pushed tag ${VERSION}"
+
+ - name: Dry run summary
+ if: ${{ github.event.inputs.dry_run == 'true' }}
+ run: |
+ echo "Dry run complete - all checks passed."
+ echo "Would have created tag: ${{ steps.checks.outputs.version }}"
run: |
cargo binstall komac@2.16.0 -y
+ # TODO: This should later be updated to publish releases instead of
+ # development release builds.
- name: Find latest release
id: find_latest_release
uses: actions/github-script@v8
project("llama.cpp" C CXX)
include(CheckIncludeFileCXX)
+### llama.cpp version
+set(LLAMA_VERSION_MAJOR 0)
+set(LLAMA_VERSION_MINOR 1)
+set(LLAMA_VERSION_PATCH 0)
+set(LLAMA_VERSION_BASE "${LLAMA_VERSION_MAJOR}.${LLAMA_VERSION_MINOR}.${LLAMA_VERSION_PATCH}")
+
+# whether this is a development/nightly build
+# set this to OFF when making a release from a release tag (vX.Y.Z)
+# ref: https://github.com/ggml-org/ggml/discussions/1579
+option(LLAMA_BUILD_IS_DEV "llama: dev build" ON)
+
+if (LLAMA_BUILD_IS_DEV)
+ set(LLAMA_VERSION "${LLAMA_VERSION_BASE}-dev")
+else()
+ # TODO: check that the current commit is tagged correctly according to the version specified above
+ set(LLAMA_VERSION "${LLAMA_VERSION_BASE}")
+endif()
+
+message(STATUS "llama.cpp version: ${LLAMA_VERSION}")
+
#set(CMAKE_WARN_DEPRECATED YES)
set(CMAKE_WARN_UNUSED_CLI YES)
set(LLAMA_STANDALONE ON)
include(git-vars)
-
- # configure project version
- # TODO
else()
set(LLAMA_STANDALONE OFF)
endif()
if (NOT DEFINED LLAMA_BUILD_COMMIT)
set(LLAMA_BUILD_COMMIT ${BUILD_COMMIT})
endif()
-set(LLAMA_INSTALL_VERSION 0.0.${LLAMA_BUILD_NUMBER})
# override ggml options
set(GGML_ALL_WARNINGS ${LLAMA_ALL_WARNINGS})
LLAMA_BIN_INSTALL_DIR )
write_basic_package_version_file(
- ${CMAKE_CURRENT_BINARY_DIR}/llama-version.cmake
- VERSION ${LLAMA_INSTALL_VERSION}
+ ${CMAKE_CURRENT_BINARY_DIR}/llama-config-version.cmake
+ VERSION ${LLAMA_VERSION}
COMPATIBILITY SameMajorVersion)
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/llama-config.cmake
- ${CMAKE_CURRENT_BINARY_DIR}/llama-version.cmake
+ ${CMAKE_CURRENT_BINARY_DIR}/llama-config-version.cmake
DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/llama)
configure_file(cmake/llama.pc.in
- [XCFramework](docs/xcframework.md)
- [Completions](docs/completions.md)
- [Models](docs/models.md)
+- [Release process](docs/release.md)
## Contributing
#include "build-info.h"
+#include "llama.h"
+
#include <cstdio>
#include <cstdlib>
#include <string>
#undef UPDATE_HIDDEN
-static int version(int argc, char ** argv) {
- printf("%s\n", llama_build_info());
+static int version(int /*argc*/, char ** /*argv*/) {
+ llama_print_build_info(llama_version());
return 0;
}
-static int licenses(int argc, char ** argv) {
+static int licenses(int /*argc*/, char ** /*argv*/) {
for (int i = 0; LICENSES[i]; ++i) {
printf("%s\n", LICENSES[i]);
}
-set(LLAMA_VERSION @LLAMA_INSTALL_VERSION@)
+set(LLAMA_VERSION @LLAMA_VERSION@)
set(LLAMA_BUILD_COMMIT @LLAMA_BUILD_COMMIT@)
set(LLAMA_BUILD_NUMBER @LLAMA_BUILD_NUMBER@)
set(LLAMA_SHARED_LIB @BUILD_SHARED_LIBS@)
Name: llama
Description: Port of Facebook's LLaMA model in C/C++
-Version: @LLAMA_INSTALL_VERSION@
+Version: @LLAMA_VERSION@
Libs: -L${libdir} -lggml -lggml-base -lllama
Cflags: -I${includedir}
)
set_target_properties(${TARGET} PROPERTIES
- VERSION ${LLAMA_INSTALL_VERSION}
- SOVERSION 0
+ VERSION ${LLAMA_VERSION_BASE}
+ SOVERSION ${LLAMA_VERSION_MAJOR}
MACHO_CURRENT_VERSION 0 # keep macOS linker from seeing oversized version number
)
{"--version"},
"show version and build info",
[](common_params &) {
- fprintf(stderr, "version: %d (%s)\n", llama_build_number(), llama_commit());
- fprintf(stderr, "built with %s for %s\n", llama_compiler(), llama_build_target());
+ llama_print_build_info(llama_version());
exit(0);
}
));
return s.c_str();
}
-void llama_print_build_info(void) {
- fprintf(stderr, "%s: build = %d (%s)\n", __func__, llama_build_number(), llama_commit());
- fprintf(stderr, "%s: built with %s for %s\n", __func__, llama_compiler(), llama_build_target());
+void llama_print_build_info(const char * llama_version) {
+ fprintf(stderr, "version: %s (build %d, commit %s)\n", llama_version, llama_build_number(), llama_commit());
+ fprintf(stderr, "built with %s for %s\n", llama_compiler(), llama_build_target());
}
const char * llama_build_target(void);
const char * llama_build_info(void);
-void llama_print_build_info(void);
+void llama_print_build_info(const char *);
--- /dev/null
+# Release process
+
+llama.cpp uses [semantic versioning](https://semver.org) (`MAJOR.MINOR.PATCH`).
+
+## Version bump guidelines
+
+| Change type | Version component |
+|---|---|
+| Breaking change to the public C API (`include/llama.h`) | `MAJOR` |
+| Backward-compatible features, model support, or API addition | `MINOR` |
+| Bug fix with no API change | `PATCH` |
+
+The version is set in the three variables at the top of the root `CMakeLists.txt`:
+
+```cmake
+set(LLAMA_VERSION_MAJOR 0)
+set(LLAMA_VERSION_MINOR 1)
+set(LLAMA_VERSION_PATCH 0)
+```
+
+_A version bump should be included in the PR that introduces the change, or in a
+dedicated bump commit merged before the release is cut._
+
+_TODO: add PR labels (`semver: patch`, `semver: minor`, `semver: major`) to help
+identify which PRs require a version bump before cutting a release._
+
+## Making a release
+
+Releases are created by running the [make-release](.github/workflows/make-release.yml)
+which is a manual workflow.
+
+The workflow creates an annotated git tag (e.g. `v0.1.0`) and pushes it to the
+remote. No GitHub Release object is created, the tag is the release artifact.
+
+## Building a release
+
+By default, `LLAMA_BUILD_IS_DEV=ON` which appends a `-dev` suffix to `LLAMA_VERSION`,
+marking the build as a nightly/development build. Distributors building from a
+release tag must pass `-DLLAMA_BUILD_IS_DEV=OFF` to produce a clean version string
+(e.g. `0.1.0` instead of `0.1.0-dev`).
+
+## How releases reach users
+Currently releases are not published to github releases, only nightly/development
+builds are available there. The way users can access releases are using the following
+channels:
+
+- **llama-install.sh** — downloads pre-built binaries built from the release tag.
+- **Package managers** — consume the git tag directly.
+- **Build from source** — users clone the repo and check out the tag.
--- /dev/null
+llama-build-install
+install
+build
--- /dev/null
+cmake_minimum_required(VERSION 3.14)
+project(llama-simple)
+
+set(CMAKE_CXX_STANDARD 17)
+
+find_package(llama 0.1.0 REQUIRED)
+
+add_executable(test-cmake test-cmake.cpp)
+target_link_libraries(test-cmake PRIVATE llama)
+target_compile_definitions(test-cmake PRIVATE
+ LLAMA_BUILD_NUMBER=${LLAMA_BUILD_NUMBER}
+ LLAMA_BUILD_COMMIT="${LLAMA_BUILD_COMMIT}"
+)
--- /dev/null
+## cmake-test
+
+This is just for manually testing/developing of a llama.cpp installation to
+enable troubleshooting issues and exploration. The idea is that this can be used
+after making changes to llama.cpp installation cmake configuration and then
+verify it locally.
+
+### Usage
+The following will configure, build, and install llama.cpp
+
+Configuring/build/install:
+```console
+./build-install.sh
+```
+The above command will create a directory named `install` in the current directory
+which will have the follwing files in its lib directory:
+```console
+(venv) $ ls install/lib/
+cmake libggml.so libllama-common.so.0 libllama.so.0.1.0 llama.cpp
+libggml-base.so libggml.so.0 libllama-common.so.0.1.0 libmtmd.so pkgconfig
+libggml-base.so.0 libggml.so.0.19.0 libllama.so libmtmd.so.0
+libggml-base.so.0.19.0 libllama-common.so libllama.so.0 libmtmd.so.0.1.0
+```
+
+Build/run this project using the installation created above:
+```console
+(venv) $ ./build.sh
+-- Configuring done (0.0s)
+-- Generating done (0.0s)
+-- Build files have been written to: /home/danbev/work/ai/llama.cpp/examples/test-cmake/build
+[100%] Built target test-cmake
+[test-cmake] Using llama.cpp version 0.1.0-dev-b10335
+[test-cmake] Initializing backend...
+load_backend: loaded CPU backend from /home/danbev/work/ai/llama.cpp/examples/test-cmake/install/lib/llama.cpp/libggml-cpu-alderlake.so
+[test-cmake] Backend initialized.
+```
--- /dev/null
+#!/bin/bash
+
+set -e
+
+rm -rf llama-build-install install
+
+cmake --fresh -S ../../. -B llama-build-install -DCMAKE_BUILD_TYPE=Release \
+ -DBUILD_SHARED_LIBS=ON \
+ -DGGML_BACKEND_DL=ON \
+ -DGGML_CPU_ALL_VARIANTS=ON \
+ -DLLAMA_TESTS_INSTALL=OFF \
+ -DCMAKE_INSTALL_PREFIX="${PWD}/install" \
+ -DGGML_BACKEND_DIR="${PWD}/install/lib/llama.cpp" \
+ -DGGML_LIB_INSTALL_DIR="${PWD}/install/lib/llama.cpp" \
+ -DLLAMA_LIB_INSTALL_DIR="${PWD}/install/lib/llama.cpp" \
+ -DLLAMA_TOOLS_INSTALL=OFF
+
+cmake --build llama-build-install --parallel 12
+cmake --install llama-build-install
--- /dev/null
+#!/bin/bash
+
+set -e
+
+cmake -S . -B build -DCMAKE_PREFIX_PATH="${PWD}/install"
+cmake --build build
+LD_LIBRARY_PATH="${PWD}/install/lib/llama.cpp:${PWD}/install/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" ./build/test-cmake
--- /dev/null
+#include "llama.h"
+#include <cstdio>
+
+int main(void) {
+ printf("[test-cmake] version: %s, build: %d (%s)\n",
+ llama_version(), LLAMA_BUILD_NUMBER, LLAMA_BUILD_COMMIT);
+ printf("[test-cmake] Initializing backend...\n");
+ llama_backend_init();
+ printf("[test-cmake] Backend initialized.\n");
+ llama_backend_free();
+ return 0;
+}
// lora adapter
struct llama_adapter_lora;
+ LLAMA_API const char * llama_version(void);
+
// Helpers for getting default parameters
// TODO: update API to start accepting pointers to params structs (https://github.com/ggml-org/llama.cpp/discussions/9172)
LLAMA_API struct llama_model_params llama_model_default_params(void);
--- /dev/null
+#!/bin/bash
+# Run all pre-release checks and determine the release version.
+#
+# Usage: make-release-checks.sh [--dry-run]
+# --dry-run: warn on failures instead of aborting
+#
+# Env (when running in GitHub Actions): GH_TOKEN, GITHUB_REPOSITORY, GITHUB_OUTPUT
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+DRY_RUN=false
+for arg in "$@"; do
+ case "$arg" in
+ --dry-run) DRY_RUN=true ;;
+ *) echo "Unknown argument: $arg"; exit 1 ;;
+ esac
+done
+
+MAJOR=$(grep "set(LLAMA_VERSION_MAJOR" "$REPO_ROOT/CMakeLists.txt" | grep -oP '\d+')
+MINOR=$(grep "set(LLAMA_VERSION_MINOR" "$REPO_ROOT/CMakeLists.txt" | grep -oP '\d+')
+PATCH=$(grep "set(LLAMA_VERSION_PATCH" "$REPO_ROOT/CMakeLists.txt" | grep -oP '\d+')
+VERSION="v${MAJOR}.${MINOR}.${PATCH}"
+echo "Determined version: ${VERSION}"
+if [[ -n "${GITHUB_OUTPUT:-}" ]]; then
+ echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+fi
+
+echo "Checking that tag ${VERSION} does not already exist..."
+if git ls-remote --tags origin "${VERSION}" | grep -q "${VERSION}"; then
+ echo "Error: tag ${VERSION} already exists on remote"
+ exit 1
+fi
+echo "Tag ${VERSION} does not exist on remote - OK"
+
+SHA=$(git rev-parse HEAD)
+echo "Checking release.yml status for commit ${SHA}..."
+if [[ -z "${GITHUB_REPOSITORY:-}" ]]; then
+ echo "Warning: GITHUB_REPOSITORY not set - skipping CI check (local run)"
+else
+ RUNS=$(gh api "repos/${GITHUB_REPOSITORY}/actions/workflows/release.yml/runs" \
+ --jq "[.workflow_runs[] | select(.head_sha == \"${SHA}\" and .conclusion == \"success\")] | length")
+ if [[ "$RUNS" -eq 0 ]]; then
+ if [[ "$DRY_RUN" == "true" ]]; then
+ echo "Warning: no successful release.yml run found for HEAD (${SHA}) (dry run, continuing)."
+ else
+ echo "Error: no successful release.yml run found for HEAD (${SHA})"
+ echo "The nightly build must complete successfully before making a release."
+ exit 1
+ fi
+ else
+ echo "Found successful release.yml run for HEAD."
+ fi
+fi
+
+MAJOR=$(grep "set(GGML_VERSION_MAJOR" "$REPO_ROOT/ggml/CMakeLists.txt" | grep -oP '\d+')
+MINOR=$(grep "set(GGML_VERSION_MINOR" "$REPO_ROOT/ggml/CMakeLists.txt" | grep -oP '\d+')
+PATCH=$(grep "set(GGML_VERSION_PATCH" "$REPO_ROOT/ggml/CMakeLists.txt" | grep -oP '\d+')
+GGML_VERSION="v${MAJOR}.${MINOR}.${PATCH}"
+echo "Local ggml version: ${GGML_VERSION}"
+
+if ! git clone --depth 1 --branch "${GGML_VERSION}" https://github.com/ggml-org/ggml.git upstream-ggml 2>/dev/null; then
+ echo "Warning: tag ${GGML_VERSION} not found in upstream ggml - skipping comparison"
+else
+ echo "Comparing local ggml/ src and include with upstream ${GGML_VERSION}..."
+ DIFF=$(diff -rq "$REPO_ROOT/ggml/src" upstream-ggml/src 2>&1 || true)
+ DIFF+=$(diff -rq "$REPO_ROOT/ggml/include" upstream-ggml/include 2>&1 || true)
+ DIFF+=$(diff "$REPO_ROOT/ggml/CMakeLists.txt" upstream-ggml/CMakeLists.txt 2>&1 || true)
+ rm -rf upstream-ggml
+ if [[ -n "$DIFF" ]]; then
+ echo "local ggml/ differs from upstream ${GGML_VERSION}:"
+ echo "$DIFF"
+ if [[ "$DRY_RUN" == "true" ]]; then
+ echo "Warning: would abort release due to ggml mismatch (dry run, continuing)."
+ else
+ echo "Error: ggml must match upstream before making a release."
+ exit 1
+ fi
+ else
+ echo "local ggml/ matches upstream ${GGML_VERSION}"
+ fi
+fi
)
set_target_properties(llama PROPERTIES
- VERSION ${LLAMA_INSTALL_VERSION}
- SOVERSION 0
+ VERSION ${LLAMA_VERSION_BASE}
+ SOVERSION ${LLAMA_VERSION_MAJOR}
MACHO_CURRENT_VERSION 0 # keep macOS linker from seeing oversized version number
)
+target_compile_definitions(llama PRIVATE
+ LLAMA_VERSION="${LLAMA_VERSION}"
+ LLAMA_COMMIT="${LLAMA_BUILD_COMMIT}"
+)
+
target_include_directories(llama PRIVATE .)
target_include_directories(llama PUBLIC ../include)
target_compile_features (llama PRIVATE cxx_std_17) # don't bump
return ggml_backend_reg_by_name("RPC") != nullptr;
}
+const char * llama_version(void) {
+ return LLAMA_VERSION;
+}
+
void llama_backend_init(void) {
ggml_time_init();
return 1;
}
- llama_print_build_info();
+ llama_print_build_info(llama_version());
// load the model
fprintf(stderr, "Loading model\n");
params.cb_eval_user_data = &cb_data;
params.warmup = false;
- llama_print_build_info();
+ llama_print_build_info(llama_version());
llama_backend_init();
llama_numa_init(params.numa);
split_print_usage(argv[0]);
exit(0);
} else if (arg == "--version") {
- fprintf(stderr, "version: %d (%s)\n", llama_build_number(), llama_commit());
+ fprintf(stderr, "version: %s (build %d, commit %s)\n", llama_version(), llama_build_number(), llama_commit());
fprintf(stderr, "built with %s for %s\n", llama_compiler(), llama_build_target());
exit(0);
} else if (arg == "--dry-run") {
)
set_target_properties(mtmd PROPERTIES
- VERSION ${LLAMA_INSTALL_VERSION}
- SOVERSION 0
+ VERSION ${LLAMA_VERSION_BASE}
+ SOVERSION ${LLAMA_VERSION_MAJOR}
MACHO_CURRENT_VERSION 0 # keep macOS linker from seeing oversized version number
)
}
}
- llama_print_build_info();
+ llama_print_build_info(llama_version());
if (params.dry_run) {
fprintf(stderr, "%s: calculating quantization size for '%s' as %s", __func__, fname_inp.c_str(), ftype_str.c_str());
overview / pkg / ggml / sources / llama.cpp / commitdiff