xt-sdk 文档 v1.0.3
xt-sdk 嵌入式 SDK API 参考
载入中...
搜索中...
未找到
xt_sdk_version - SDK 版本号

版本：0.1 | 日期：2026-04-23 | 路径： components/xt_sdk_version/

一、概述

xt_sdk_version 为整个 xt-sdk 提供统一的版本信息查询接口。它将"版本号定义"与"构建时环境注入"分离——头文件维护人工可读的语义版本号，xmake 构建脚本在编译期自动注入 Git 提交哈希、平台标识、脏标记等运行时信息，使每个编译产物都能追溯其来源。

1.1 设计原则

  • **编译期注入**：所有版本信息以宏定义形式存在于编译期，零运行时开销
  • **双源分离**：语义版本号（MAJOR.MINOR.PATCH）由头文件人工维护，Git/平台信息由 xmake 自动注入
  • **原子标记**： >>> XT_SDK_VERSION_BEGIN <<< / >>> XT_SDK_VERSION_END <<< 标记对供自动化脚本定位并 bump 版本号
  • **查询函数薄封装**：C 函数仅返回对应宏值，便于跨编译单元和 ABI 边界传递

1.2 依赖

依赖 用途
stdint.h uint32_t / uint8_t 类型

二、核心概念

2.1 版本号编码

版本号以两种形式提供：

形式 宏 值示例（v1.0.3）
数值 XT_SDK_VERSION_NUM (1 << 16) + (0 << 8) + 3 = 0x010003
字符串 XT_SDK_VERSION "v1.0.3"

数值形式适合做 #if XT_SDK_VERSION_NUM >= 0x010000 版本判断；字符串形式适合日志输出和版本展示。

2.2 构建时注入的宏

以下宏**不出现在头文件中**，由 xmake.lua 的 on_config 回调在编译期注入：

宏 来源 说明
XT_SDK_PLATFORM xmake 配置 平台字符串（如 "windows" 、 "esp32" ）
XT_SDK_PLATFORM_<NAME> xmake 配置 平台枚举宏，值为 1
XT_SDK_TARGET xmake 配置 目标字符串（如 "simulator" ）
XT_SDK_TARGET_<NAME> xmake 配置 目标枚举宏，值为 1
XT_SDK_GIT_VERSION Git 仓库 提交哈希，不干净时附加 -dirty
XT_SDK_IS_DIRTY Git 仓库 1 表示有未提交修改
XT_SDK_PLATFORM_GIT_VERSION 平台仓库 平台仓库提交哈希；非独立仓库时回退到 XT_SDK_GIT_VERSION
XT_SDK_PLATFORM_IS_DIRTY 平台仓库 1 表示平台仓库不干净；非独立仓库时回退到 XT_SDK_IS_DIRTY
XT_SDK_IS_TAGGED Git 仓库 1 表示当前 HEAD 被某 tag 精确指向

头文件中 #if 0 块展示了这些宏的示例值，仅供文档参考，实际值由构建系统覆盖。

2.3 SDK 版本与平台版本的区分

xt-sdk 支持平台代码独立仓库管理。当平台是独立仓库时， XT_SDK_GIT_VERSION 和 XT_SDK_PLATFORM_GIT_VERSION 分别指向各自仓库的提交；当平台不是独立仓库（合并在 SDK 仓库中）时，平台版本信息回退到 SDK 版本。

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_sdk_version（SDK 版本号） 。

3.1 版本查询函数

函数签名 说明
uint32_t xt_sdk_get_version(void) 获取 SDK 版本号（数值形式，MAJOR<<16 | MINOR<<8 | PATCH）
const char * xt_sdk_get_version_str(void) 获取 SDK 版本号字符串（"vMAJOR.MINOR.PATCH"）
const char * xt_sdk_get_git_version(void) 获取 SDK Git 提交哈希（不干净时附加 -dirty）
uint8_t xt_sdk_get_is_dirty(void) 获取 SDK 仓库是否有未提交修改（0=干净，1=脏）
const char * xt_sdk_get_platform_git_version(void) 获取平台 Git 提交哈希
uint8_t xt_sdk_get_platform_is_dirty(void) 获取平台仓库是否有未提交修改

3.2 版本号宏

宏签名 说明
XT_SDK_VERSION_MAJOR 主版本号
XT_SDK_VERSION_MINOR 次版本号
XT_SDK_VERSION_PATCH 补丁版本号
XT_SDK_VERSION_NUM 版本号数值（MAJOR<<16 + MINOR<<8 + PATCH）
XT_SDK_VERSION 版本号字符串（"vMAJOR.MINOR.PATCH"）

共 6 个查询函数，分别返回版本号数值、版本号字符串、Git 版本、脏标记、平台 Git 版本、平台脏标记。

四、常见模式

4.1 启动日志输出版本信息

#include "xt_sdk_version.h"
void print_banner(void)
{
printf("XT-SDK %s (git: %s%s)\n",
xt_sdk_get_version_str(),
xt_sdk_get_git_version(),
xt_sdk_get_is_dirty() ? " [dirty]" : "");
printf("Platform: %s git: %s\n",
"", /* XT_SDK_PLATFORM 可直接使用 */
xt_sdk_get_platform_git_version());
}
xt_sdk_get_version_str
const char * xt_sdk_get_version_str(void)
获取SDK版本号（字符串形式）
xt_sdk_get_git_version
const char * xt_sdk_get_git_version(void)
获取SDK Git版本信息
xt_sdk_get_platform_git_version
const char * xt_sdk_get_platform_git_version(void)
获取平台Git版本信息
xt_sdk_get_is_dirty
uint8_t xt_sdk_get_is_dirty(void)
获取SDK仓库是否有未提交修改
xt_sdk_version.h
XTINY SDK 版本定义与查询接口

4.2 编译期版本检查

#if XT_SDK_VERSION_NUM < ((1 << 16) + (0 << 8) + 3)
#error "需要 XT-SDK v1.0.3 或以上版本"
#endif

4.3 平台条件编译

#ifdef XT_SDK_PLATFORM_WINDOWS
/* Windows 专属代码 */
#endif
#ifdef XT_SDK_TARGET_SIMULATOR
/* 模拟器专属代码 */
#endif

五、反模式

反模式 问题 正确做法
手动修改 XT_SDK_GIT_VERSION 等宏 下次构建被 xmake 覆盖 通过构建系统配置注入
在头文件 #if 0 块中添加真实宏 编译时不会生效 使用 xmake 配置或命令行 -D 传入
用 xt_sdk_get_version_str() 做版本比较 字符串比较不可靠 用 xt_sdk_get_version() 数值比较

六、版本号维护

头文件中 >>> XT_SDK_VERSION_BEGIN <<< 和 >>> XT_SDK_VERSION_END <<< 标记之间的三行是版本号定义区：

/* >>> XT_SDK_VERSION_BEGIN <<< */
#define XT_SDK_VERSION_MAJOR 1
#define XT_SDK_VERSION_MINOR 0
#define XT_SDK_VERSION_PATCH 3
/* >>> XT_SDK_VERSION_END <<< */

自动化发版脚本可通过这两个标记精确定位并修改版本号，无需解析整个文件。