版本：0.1 | 日期：2026-07-03 | 路径： platforms/components/xtiny/xt_platform_version/

一、概述

xt_platform_version 是 xtiny 平台版本查询模块，只提供一个函数—— xt_platform_get_version 。运行时调用即可获得编译时自动注入的 Git 版本字符串，用于日志记录、固件上报、OTA 版本比对等场景。

设计理念： 零配置，全自动 。用户无需手动维护版本号——构建系统在编译时通过 git describe 和 git rev-parse 自动生成版本头文件，注入到二进制中。

1.1 设计原则

单函数接口 ：语义明确，无学习成本
编译时注入 ：版本号在构建时从 git 元数据生成，运行时零开销
不可变返回值 ：返回的字符串指向静态常量区，调用者无需释放

1.2 依赖

无外部依赖。不包含任何头文件（ xt_platform_version_defs.h 由构建系统自动生成）。

二、核心概念

2.1 版本字符串格式

版本字符串由构建系统在编译时注入版本字符串，格式为 "<tag>-<hash>" ：

场景	版本字符串示例	说明
打 tag 的正式版本	v01.02-3d08ea4a	当前 HEAD 匹配 vxx.yy 格式的 tag
无 tag 的开发版本	unknown-3d08ea4a	当前 HEAD 无匹配 tag，但 git 可用
git 不可用	unknown-unknown	构建环境无 git 或源码不在仓库中

2.2 构建时注入机制

构建时从 git 元数据自动生成版本字符串并注入编译产物，无需手动维护版本号。

三、API 参考

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

3.1 版本查询

函数签名	说明
const char *xt_platform_get_version(void)	获取平台版本字符串，返回静态常量指针，无需释放

四、编译配置

无用户配置宏。版本号完全由构建系统根据 git 元数据自动生成。

五、常见模式

5.1 启动时输出版本

#include "xtiny.h"
 
void app_init(void)
{
    xt_printf("platform version: %s\n", xt_platform_get_version());
    // 输出示例: platform version: v01.02-3d08ea4a
}

5.2 OTA 升级版本上报

void ota_report_version(void)
{
    const char *ver = xt_platform_get_version();
    xt_mobile_report_firmware_version(ver);
}

5.3 调试日志附加版本

#define XT_LOGE(tag, fmt, ...) \

xt_printf("[E][%s] %s: " fmt "\n", xt_platform_get_version(), tag, ##__VA_ARGS__)

六、反模式

反模式	问题	正确做法
对返回值调 free	返回的是静态常量区指针，释放会导致崩溃	直接使用，无需释放
缓存返回值到局部变量	字符串常量不会变，但无坏处	每次调用 xt_platform_get_version 即可
依赖版本字符串格式解析	格式可能随构建系统调整	仅当不透明字符串使用，不要解析内部结构

七、已知行为与限制

行为	说明
git 不可用时返回 unknown-unknown	离线构建或非 git 环境的兜底值
tag 匹配规则为 vxx.yy	版本号须为两位点分数字（如 v03.05 ）
返回值指向只读内存	跨线程安全，无需加锁
每次调用返回同一地址	内部实现为常量字符串，可反复调用