feat: Add SENTRY_SDK_VERSION CMake override for downstream SDKs (#1417)

* feat: Auto-split build ID from version in sentry_library_info

When downstream SDKs modify sentry.h to include build metadata in the
version string (e.g., 0.11.3+20251016-9e31c9f-dirty), the embedded
library info now automatically extracts the build ID from the version.

Changes:
- Parse build metadata from SENTRY_VERSION_FULL if present
- Use base version (major.minor.patch) for SENTRY_VERSION field
- Use extracted build ID for BUILD field
- SENTRY_BUILD_ID cache variable still takes precedence
- Update template to use new SENTRY_EMBEDDED_VERSION and SENTRY_EMBEDDED_BUILD_ID
- Update tests to validate base version format
- Add test for build ID field

This ensures the embedded info format is:
SENTRY_VERSION:0.11.3;BUILD:20251016-9e31c9f-dirty
instead of:
SENTRY_VERSION:0.11.3+20251016-9e31c9f-dirty;BUILD:0.11.3+20251016-9e31c9f-dirty

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* refactor: Use SENTRY_VERSION_BASE directly instead of SENTRY_EMBEDDED_VERSION

Simplifies the code by reusing the existing SENTRY_VERSION_BASE variable
which already contains the major.minor.patch format without build metadata.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* refactor: Skip parsing if SENTRY_BUILD_ID is already set

Optimizes the logic to check SENTRY_BUILD_ID cache variable first.
Only attempts to extract build ID from version string if not explicitly provided.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* refactor: Simplify build ID logic with if-elseif-else chain

Cleaner and more readable conditional structure.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* fix: Use semver-compliant format for default build ID timestamp

According to semver.org spec, build metadata must contain only ASCII
alphanumerics and hyphens [0-9A-Za-z-]. Spaces are not allowed.

Changed from: "2025-10-17 10:59:00 UTC"
Changed to: "20251017-105900"

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* docs: Add changelog entry for automatic build ID extraction

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* feat: Add SENTRY_SDK_VERSION cache variable for downstream SDK override

Downstream SDKs can now override the SDK version at CMake configuration time
using -DSENTRY_SDK_VERSION="version+build-id". This allows setting the version
without modifying sentry.h.

When SENTRY_SDK_VERSION is set:
- The full version (with build metadata) is used for embedded library info
- Build ID is automatically extracted from the version string
- sentry.h uses the overridden version via compile definition
- Version parsing happens at CMake configuration time

Example usage:
cmake -DSENTRY_SDK_VERSION="0.11.3+20251016-9e31c9f-dirty" ...

Results in embedded info:
SENTRY_VERSION:0.11.3;BUILD:20251016-9e31c9f-dirty;...

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* fix: Check SENTRY_SDK_VERSION for empty string instead of truthiness

Aligns with the pattern used for SENTRY_SDK_NAME check.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* fix: Use SENTRY_SDK_VERSION directly for compile definitions instead of SENTRY_VERSION_FULL

* test: Add Python tests for SENTRY_SDK_VERSION override

Added two new integration tests:

1. test_sdk_version_override: Verifies that setting SENTRY_SDK_VERSION
   correctly separates version and build ID in the embedded library info.

2. test_sdk_version_override_with_explicit_build_id: Verifies that
   explicit SENTRY_BUILD_ID takes precedence over extracted build ID
   from the version string.

Both tests inspect the actual binary using the strings command to
validate the embedded information.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* fix: Update regex to handle whitespace before SENTRY_SDK_VERSION define

The #ifndef guard adds leading whitespace to the #define line, so the
regex needs to handle optional leading whitespace and whitespace between
tokens.

This fixes the issue where CMake couldn't parse the version from sentry.h
when SENTRY_SDK_VERSION was not overridden.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* fix: Update changelog entry for SENTRY_SDK_VERSION CMake cache variable to clarify build ID extraction

---------

Co-authored-by: Claude <[email protected]>

Author: vaind

CHANGELOG.md

@@ -6,6 +6,10 @@
 
 - Add logs flush on crash. This is not available for macOS with the `crashpad` backend. ([#1404](https://github.com/getsentry/sentry-native/pull/1404))
 
+**Internal**:
+
+- Add `SENTRY_SDK_VERSION` CMake cache variable to allow downstream SDKs to override the SDK version at configuration time. ([#1417](https://github.com/getsentry/sentry-native/pull/1417))
+
 ## 0.11.3
 
 **Features**:

CMakeLists.txt

@@ -9,20 +9,34 @@ else()
 	cmake_policy(SET CMP0077 NEW)
 endif()
 
-# Extract version string from SENTRY_SDK_VERSION define in sentry.h
-file(READ "include/sentry.h" _VERSION_STR_TMP)
-# Supports full semver format including prerelease and build metadata
-string(REGEX MATCH "#define SENTRY_SDK_VERSION \"([^\"]+)\"" _VERSION_STR_TMP "${_VERSION_STR_TMP}")
-set(SENTRY_VERSION_FULL "${CMAKE_MATCH_1}")
+# Allow downstream SDKs to override the SDK version at CMake configuration time
+set(SENTRY_SDK_VERSION "" CACHE STRING "Override the SDK version (supports full semver format with build metadata)")
+
+# Extract version string from SENTRY_SDK_VERSION cache variable or sentry.h
+if(NOT SENTRY_SDK_VERSION STREQUAL "")
+	set(SENTRY_VERSION_FULL "${SENTRY_SDK_VERSION}")
+else()
+	file(READ "include/sentry.h" _VERSION_STR_TMP)
+	# Supports full semver format including prerelease and build metadata
+	# The regex handles optional leading whitespace for the #define
+	string(REGEX MATCH "#[ \t]*define[ \t]+SENTRY_SDK_VERSION[ \t]+\"([^\"]+)\"" _VERSION_STR_TMP "${_VERSION_STR_TMP}")
+	set(SENTRY_VERSION_FULL "${CMAKE_MATCH_1}")
+	unset(_VERSION_STR_TMP)
+endif()
+
 # Extract just the major.minor.patch part from the full version
-string(REGEX MATCH "^([0-9]+)\\.([0-9]+)\\.([0-9]+)" _VERSION_STR_TMP "${SENTRY_VERSION_FULL}")
+string(REGEX MATCH "^([0-9]+)\\.([0-9]+)\\.([0-9]+)" _VERSION_PARSE_TMP "${SENTRY_VERSION_FULL}")
 set(SENTRY_VERSION_MAJOR "${CMAKE_MATCH_1}")
 set(SENTRY_VERSION_MINOR "${CMAKE_MATCH_2}")
 set(SENTRY_VERSION_PATCH "${CMAKE_MATCH_3}")
 set(SENTRY_VERSION_BASE "${SENTRY_VERSION_MAJOR}.${SENTRY_VERSION_MINOR}.${SENTRY_VERSION_PATCH}")
-unset(_VERSION_STR_TMP)
+unset(_VERSION_PARSE_TMP)
 
-message(STATUS "Sentry SDK version (full): ${SENTRY_VERSION_FULL}")
+if(NOT SENTRY_SDK_VERSION STREQUAL "")
+	message(STATUS "Sentry SDK version (full): ${SENTRY_VERSION_FULL} (overridden via SENTRY_SDK_VERSION)")
+else()
+	message(STATUS "Sentry SDK version (full): ${SENTRY_VERSION_FULL}")
+endif()
 message(STATUS "Sentry SDK version (base): ${SENTRY_VERSION_BASE}")
 message(STATUS "Sentry SDK version major='${SENTRY_VERSION_MAJOR}' minor='${SENTRY_VERSION_MINOR}' patch='${SENTRY_VERSION_PATCH}'")
 
@@ -322,9 +336,17 @@ add_library(sentry::sentry ALIAS sentry)
 
 # Configure version embedding if enabled
 if(SENTRY_EMBED_INFO)
-	# Use timestamp as default build ID if not specified
-	if(NOT SENTRY_BUILD_ID)
-		string(TIMESTAMP SENTRY_BUILD_ID "%Y-%m-%d %H:%M:%S UTC" UTC)
+	# SENTRY_BUILD_ID cache variable takes precedence
+	if(SENTRY_BUILD_ID)
+		set(SENTRY_EMBEDDED_BUILD_ID "${SENTRY_BUILD_ID}")
+	elseif(SENTRY_VERSION_FULL MATCHES "^[0-9]+\\.[0-9]+\\.[0-9]+\\+(.+)$")
+		# Extract build ID from SENTRY_VERSION_FULL if present (format: major.minor.patch+build-id)
+		# This handles cases where downstream SDKs modify sentry.h to include build metadata
+		set(SENTRY_EMBEDDED_BUILD_ID "${CMAKE_MATCH_1}")
+	else()
+		# No build ID found in version or provided, use timestamp as default
+		# Format: YYYYMMDD-HHMMSS (semver-compliant: alphanumerics and hyphens only)
+		string(TIMESTAMP SENTRY_EMBEDDED_BUILD_ID "%Y%m%d-%H%M%S" UTC)
 	endif()
 
 	# Validate and escape special characters in custom items if needed
@@ -367,6 +389,12 @@ if (NOT SENTRY_SDK_NAME STREQUAL "")
 	target_compile_definitions(sentry PRIVATE SENTRY_SDK_NAME="${SENTRY_SDK_NAME}")
 endif()
 
+# If SDK version was overridden via CMake, pass it as a compile definition
+# This allows sentry.h to use the overridden version
+if (NOT SENTRY_SDK_VERSION STREQUAL "")
+	target_compile_definitions(sentry PRIVATE SENTRY_SDK_VERSION="${SENTRY_SDK_VERSION}")
+endif()
+
 # we do not need this on android, only linux
 if(LINUX)
 	target_sources(sentry PRIVATE

include/sentry.h

@@ -78,7 +78,9 @@ extern "C" {
 #        define SENTRY_SDK_NAME "sentry.native"
 #    endif
 #endif
-#define SENTRY_SDK_VERSION "0.11.3"
+#ifndef SENTRY_SDK_VERSION
+#    define SENTRY_SDK_VERSION "0.11.3"
+#endif
 #define SENTRY_SDK_USER_AGENT SENTRY_SDK_NAME "/" SENTRY_SDK_VERSION
 
 /* marks a function as part of the sentry API */

src/sentry_embedded_info.cpp.in

@@ -6,9 +6,9 @@ extern "C" SENTRY_API const char sentry_library_info[];
 
 // Definition
 extern "C" SENTRY_API const char sentry_library_info[] =
-    "SENTRY_VERSION:" SENTRY_SDK_VERSION ";"
+    "SENTRY_VERSION:@SENTRY_VERSION_BASE@;"
     "PLATFORM:@SENTRY_BUILD_PLATFORM@;"
-    "BUILD:@SENTRY_BUILD_ID@;"
+    "BUILD:@SENTRY_EMBEDDED_BUILD_ID@;"
     "VARIANT:@SENTRY_BUILD_VARIANT@;"
     "CONFIG:@CMAKE_BUILD_TYPE@;"
     "@SENTRY_EMBED_INFO_ITEMS@"

tests/test_embedded_info.py

@@ -150,3 +150,95 @@ def test_embedded_info_custom_items(cmake):
         check=True,
         env=env,
     )
+
+
+@pytest.mark.skipif(not has_http, reason="test needs http transport (curl)")
+def test_sdk_version_override(cmake):
+    """Test that SENTRY_SDK_VERSION override works correctly"""
+    cwd = cmake(
+        ["sentry"],
+        {
+            "SENTRY_EMBED_INFO": "ON",
+            "SENTRY_BUILD_PLATFORM": "version-test",
+            "SENTRY_BUILD_VARIANT": "override",
+            "SENTRY_SDK_VERSION": "0.11.3+20251016-test-build",
+        },
+    )
+
+    # Find the library file
+    library_file = None
+    for file in os.listdir(cwd):
+        if file.startswith("libsentry") and (
+            file.endswith(".so") or file.endswith(".dylib") or file.endswith(".dll")
+        ):
+            library_file = os.path.join(cwd, file)
+            break
+
+    if library_file is None:
+        pytest.skip("Could not find sentry library file")
+
+    # Use strings command to check embedded content
+    try:
+        result = subprocess.run(
+            ["strings", library_file], capture_output=True, text=True, check=True
+        )
+        output = result.stdout
+
+        # Verify that version and build ID are correctly separated
+        assert (
+            "SENTRY_VERSION:0.11.3;" in output
+        ), "Version should be base version without build metadata"
+        assert (
+            "BUILD:20251016-test-build;" in output
+        ), "Build ID should be extracted from version string"
+        assert "PLATFORM:version-test" in output
+        assert "VARIANT:override" in output
+
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        pytest.skip("strings command not available or failed")
+
+
+@pytest.mark.skipif(not has_http, reason="test needs http transport (curl)")
+def test_sdk_version_override_with_explicit_build_id(cmake):
+    """Test that explicit SENTRY_BUILD_ID takes precedence over extracted build ID"""
+    cwd = cmake(
+        ["sentry"],
+        {
+            "SENTRY_EMBED_INFO": "ON",
+            "SENTRY_BUILD_PLATFORM": "version-test",
+            "SENTRY_BUILD_VARIANT": "explicit-build",
+            "SENTRY_SDK_VERSION": "0.11.3+20251016-ignored",
+            "SENTRY_BUILD_ID": "explicit-build-id",
+        },
+    )
+
+    # Find the library file
+    library_file = None
+    for file in os.listdir(cwd):
+        if file.startswith("libsentry") and (
+            file.endswith(".so") or file.endswith(".dylib") or file.endswith(".dll")
+        ):
+            library_file = os.path.join(cwd, file)
+            break
+
+    if library_file is None:
+        pytest.skip("Could not find sentry library file")
+
+    # Use strings command to check embedded content
+    try:
+        result = subprocess.run(
+            ["strings", library_file], capture_output=True, text=True, check=True
+        )
+        output = result.stdout
+
+        # Verify that explicit build ID takes precedence
+        assert "SENTRY_VERSION:0.11.3;" in output, "Version should be base version"
+        assert (
+            "BUILD:explicit-build-id;" in output
+        ), "Explicit build ID should take precedence"
+        assert (
+            "BUILD:20251016-ignored" not in output
+        ), "Extracted build ID should not be used"
+
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        pytest.skip("strings command not available or failed")

tests/unit/test_embedded_info.c

@@ -86,15 +86,51 @@ SENTRY_TEST(embedded_info_sentry_version)
     // Version should contain at least one dot (e.g., "0.10.0")
     TEST_CHECK(strchr(embedded_version, '.') != NULL);
 
-    // Test that it matches the actual SDK version
-    TEST_CHECK_STRING_EQUAL(embedded_version, SENTRY_SDK_VERSION);
+    // Test that embedded version is the base version (major.minor.patch)
+    // It should NOT contain build metadata (e.g., +build-id)
+    TEST_CHECK(strchr(embedded_version, '+') == NULL);
+
+    // Verify embedded version starts with the same prefix as SENTRY_SDK_VERSION
+    // (handles cases where SENTRY_SDK_VERSION may include build metadata)
+    size_t embedded_len = strlen(embedded_version);
+    TEST_CHECK(
+        strncmp(embedded_version, SENTRY_SDK_VERSION, embedded_len) == 0);
 
     free(embedded_version);
 #else
     SKIP_TEST();
 #endif
 }
 
+SENTRY_TEST(embedded_info_build_id)
+{
+#ifdef SENTRY_EMBED_INFO
+    // Test that BUILD field is present and non-empty
+    const char *build_field = strstr(sentry_library_info, "BUILD:");
+    TEST_ASSERT(build_field != NULL);
+
+    // Extract the build ID value
+    const char *build_start = build_field + strlen("BUILD:");
+    const char *build_end = strchr(build_start, ';');
+    TEST_ASSERT(build_end != NULL);
+
+    size_t build_len = build_end - build_start;
+    TEST_ASSERT(build_len > 0);
+
+    // Build ID should not be empty
+    char *build_id = malloc(build_len + 1);
+    TEST_ASSERT(build_id != NULL);
+    strncpy(build_id, build_start, build_len);
+    build_id[build_len] = '\0';
+
+    TEST_CHECK(strlen(build_id) > 0);
+
+    free(build_id);
+#else
+    SKIP_TEST();
+#endif
+}
+
 SENTRY_TEST(embedded_info_disabled)
 {
 #ifndef SENTRY_EMBED_INFO

tests/unit/tests.inc

@@ -69,6 +69,7 @@ XX(dsn_with_non_http_scheme_is_invalid)
 XX(dsn_without_project_id_is_invalid)
 XX(dsn_without_url_scheme_is_invalid)
 XX(embedded_info_basic)
+XX(embedded_info_build_id)
 XX(embedded_info_disabled)
 XX(embedded_info_format)
 XX(embedded_info_sentry_version)