590 lines
18 KiB
Markdown
590 lines
18 KiB
Markdown
# ARCS SDK 版本管理说明
|
||
|
||
## 文档目的
|
||
|
||
本文档说明了 ARCS SDK 的版本管理机制和使用方法。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [概述](#概述)
|
||
2. [版本号组成](#版本号组成)
|
||
3. [文件结构](#文件结构)
|
||
4. [数据流转](#数据流转)
|
||
5. [版本变量参考](#版本变量参考)
|
||
6. [构建集成](#构建集成)
|
||
7. [版本检查机制](#版本检查机制)
|
||
8. [使用示例](#使用示例)
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
### 设计理念
|
||
|
||
- **单一数据源**: 所有版本号定义在单个纯文本文件 (`VERSION`) 中
|
||
- **多种表示形式**: 版本号以多种格式编码（字符串、整数、十六进制）
|
||
- **编译时生成**: 在 CMake 配置阶段生成版本头文件
|
||
- **Git 集成**: 可选的 git 提交哈希作为构建版本标识
|
||
|
||
### 主要特性
|
||
|
||
- 语义化版本控制，支持可选的 TWEAK 组件
|
||
- 额外版本后缀支持（如 `-rc1`、`-beta`）
|
||
- 为嵌入式系统提供十六进制版本编码
|
||
- 人类可读和机器可比较的格式
|
||
- 在 boot_banner 中自动显示版本信息
|
||
|
||
---
|
||
|
||
## 版本号组成
|
||
|
||
### 四级版本方案
|
||
|
||
```
|
||
MAJOR.MINOR.PATCH.TWEAK[-EXTRA]
|
||
1 . 10 . 0 . 0 [-rc1]
|
||
│ │ │ │ └─ 可选后缀（alpha、beta、rc1 等）
|
||
│ │ │ └──────── 构建/微调版本号（通常为 0）
|
||
│ │ └────────────── Bug 修复、补丁
|
||
│ └──────────────────── 新功能（向后兼容）
|
||
└────────────────────────── 破坏性变更
|
||
```
|
||
|
||
### 组件说明
|
||
|
||
| 组件 | 变量名 | 用途 | 何时递增 |
|
||
|-----------|---------------|---------|-------------------|
|
||
| MAJOR | `VERSION_MAJOR` | 破坏性 API 变更 | 引入 API 不兼容时 |
|
||
| MINOR | `VERSION_MINOR` | 新功能 | 添加向后兼容的新功能时 |
|
||
| PATCH | `PATCHLEVEL` | Bug 修复 | 仅修复 Bug 时 |
|
||
| TWEAK | `VERSION_TWEAK` | 构建/修订号 | 非常小的变更，通常为 0 |
|
||
| EXTRA | `EXTRAVERSION` | 预发布标签 | 预发布版本（rc1、beta 等） |
|
||
|
||
### 版本字符串格式
|
||
|
||
不同场景需要不同的版本表示形式:
|
||
|
||
| 格式 | 示例 | 用途 |
|
||
|--------|---------|-------|
|
||
| 标准（3 段） | `1.10.0` | 正式发布版本（TWEAK=0） |
|
||
| 完整（4 段） | `1.10.0.1` | 开发构建版本（TWEAK>0） |
|
||
| 带后缀 | `1.10.0-rc1` | 预发布版本 |
|
||
| 十六进制 | `0x010A00` | C 代码中的版本比较 |
|
||
| 整数 | `68096` | 数值比较 |
|
||
|
||
### 开发构建版本 vs 正式发布版本
|
||
|
||
通过 `VERSION_TWEAK` 和 `EXTRAVERSION` 区分不同阶段的版本：
|
||
|
||
| 版本类型 | TWEAK | EXTRAVERSION | 显示格式 | 使用场景 |
|
||
|---------|-------|--------------|----------|---------|
|
||
| 正式发布 | 0 | 0 | `1.10.0` | 对外发布的稳定版本 |
|
||
| 开发构建 | 1, 2, 3... | 0 | `1.10.0.1` | 日常开发、内部测试 |
|
||
| Alpha内测 | 0 | alpha | `1.10.0-alpha` | 早期内部测试 |
|
||
| Beta公测 | 0 | beta | `1.10.0-beta` | 公开测试版本 |
|
||
| RC候选 | 0 | rc1, rc2... | `1.10.0-rc1` | 发布前的候选版本 |
|
||
|
||
**典型版本演进流程**:
|
||
```
|
||
1.10.0.1 → 1.10.0.2 → ... → 1.10.0-alpha → 1.10.0-beta → 1.10.0-rc1 → 1.10.0
|
||
```
|
||
|
||
**版本显示规则**:
|
||
1. 如果设置了 `EXTRAVERSION`（非0），显示 `MAJOR.MINOR.PATCH-EXTRA`（忽略 TWEAK）
|
||
- 示例: `TWEAK=1, EXTRAVERSION=rc1` → 显示 `1.10.0-rc1`
|
||
2. 如果设置了 `TWEAK`（非0），显示 `MAJOR.MINOR.PATCH.TWEAK`
|
||
- 示例: `TWEAK=1, EXTRAVERSION=0` → 显示 `1.10.0.1`
|
||
3. 正式版本（TWEAK=0, EXTRAVERSION=0），显示 `MAJOR.MINOR.PATCH`
|
||
- 示例: `TWEAK=0, EXTRAVERSION=0` → 显示 `1.10.0`
|
||
|
||
**注意**: `SDK_VERSION_NUMBER` 不包含 `TWEAK`，因此 `1.10.0` 和 `1.10.0.1` 的版本比较值相同。如需区分开发构建，使用 `SDKVERSION`（包含32位完整编码）。
|
||
|
||
---
|
||
|
||
## 文件结构
|
||
|
||
### 核心文件
|
||
|
||
```
|
||
arcs-sdk/
|
||
├── VERSION # [源文件] 版本定义文件
|
||
├── sdk_version.h.in # [模板] C 头文件模板
|
||
├── cmake/
|
||
│ ├── version.cmake # [解析器] 解析 VERSION 并设置变量
|
||
│ ├── gen_version_h.cmake # [生成器] 生成 C 头文件
|
||
│ ├── hex.cmake # [工具] 十六进制转换函数
|
||
│ └── listenai-cmake-config.cmake # [入口] 包含 version.cmake
|
||
└── startup/arcs/sysmain.c # [使用] boot_banner 打印版本
|
||
```
|
||
|
||
### 文件关系图
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[VERSION] -->|读取| B[version.cmake]
|
||
B -->|设置变量| C[CMake 变量]
|
||
C -->|传递给| D[gen_version_h.cmake]
|
||
E[sdk_version.h.in] -->|模板| D
|
||
D -->|生成| F[sdk_version.h]
|
||
G[Git] -->|可选| D
|
||
B -->|使用| H[hex.cmake]
|
||
F -->|包含| I[sysmain.c]
|
||
I -->|显示| J[boot_banner]
|
||
```
|
||
|
||
---
|
||
|
||
## 数据流转
|
||
|
||
### 第 1 步: 版本定义（VERSION 文件）
|
||
|
||
**文件**: `VERSION`
|
||
**位置**: SDK 根目录
|
||
**格式**: 键值对
|
||
|
||
```makefile
|
||
VERSION_MAJOR = 1
|
||
VERSION_MINOR = 10
|
||
PATCHLEVEL = 0
|
||
VERSION_TWEAK = 0
|
||
EXTRAVERSION = 0
|
||
```
|
||
|
||
**规则**:
|
||
- 纯文本文件（非 YAML/JSON）
|
||
- 每行一个定义
|
||
- 仅数值（EXTRAVERSION 可以是字母数字）
|
||
- EXTRAVERSION: 正式版本使用 `0`，预发布版本使用 `rc1`/`beta`/`alpha`
|
||
|
||
### 第 2 步: 版本解析（version.cmake）
|
||
|
||
**文件**: `cmake/version.cmake`
|
||
**被包含于**: `cmake/listenai-cmake-config.cmake:58`
|
||
|
||
**处理流程**:
|
||
|
||
```cmake
|
||
# 1. 读取 VERSION 文件
|
||
file(READ ${ARCS_SDK_BASE}/VERSION ver)
|
||
|
||
# 2. 使用正则表达式解析每个组件
|
||
string(REGEX MATCH "VERSION_MAJOR = ([0-9]*)" _ ${ver})
|
||
set(PROJECT_VERSION_MAJOR ${CMAKE_MATCH_1})
|
||
|
||
string(REGEX MATCH "VERSION_MINOR = ([0-9]*)" _ ${ver})
|
||
set(PROJECT_VERSION_MINOR ${CMAKE_MATCH_1})
|
||
|
||
string(REGEX MATCH "PATCHLEVEL = ([0-9]*)" _ ${ver})
|
||
set(PROJECT_VERSION_PATCH ${CMAKE_MATCH_1})
|
||
|
||
string(REGEX MATCH "VERSION_TWEAK = ([0-9]*)" _ ${ver})
|
||
set(PROJECT_VERSION_TWEAK ${CMAKE_MATCH_1})
|
||
|
||
string(REGEX MATCH "EXTRAVERSION = ([a-z0-9]*)" _ ${ver})
|
||
set(PROJECT_VERSION_EXTRA ${CMAKE_MATCH_1})
|
||
|
||
# 3. 构建组合版本
|
||
set(PROJECT_VERSION_WITHOUT_TWEAK ${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${PROJECT_VERSION_PATCH})
|
||
|
||
# 4. 处理 TWEAK（可选的第 4 段）
|
||
if(PROJECT_VERSION_TWEAK AND NOT PROJECT_VERSION_TWEAK EQUAL 0)
|
||
set(PROJECT_VERSION ${PROJECT_VERSION_WITHOUT_TWEAK}.${PROJECT_VERSION_TWEAK})
|
||
else()
|
||
set(PROJECT_VERSION ${PROJECT_VERSION_WITHOUT_TWEAK})
|
||
endif()
|
||
|
||
# 5. 构建版本字符串（用于显示）
|
||
if(PROJECT_VERSION_EXTRA AND NOT PROJECT_VERSION_EXTRA STREQUAL "0")
|
||
set(SDK_VERSION_STRING "\"${PROJECT_VERSION_WITHOUT_TWEAK}-${PROJECT_VERSION_EXTRA}\"")
|
||
else()
|
||
set(SDK_VERSION_STRING "\"${PROJECT_VERSION_WITHOUT_TWEAK}\"")
|
||
endif()
|
||
```
|
||
|
||
**重要提示**: `SDK_VERSION_STRING` 不包含 TWEAK，仅包含 EXTRA 后缀。
|
||
|
||
### 第 3 步: 数值编码
|
||
|
||
**目的**: 使 C 代码中能进行版本比较
|
||
|
||
```cmake
|
||
# 转换为整数（24 位编码: MAJOR.MINOR.PATCH）
|
||
# 格式: 0xMMNNPP (MM=主版本, NN=次版本, PP=补丁)
|
||
math(EXPR SDK_VERSION_NUMBER_INT "(${MAJOR} << 16) + (${MINOR} << 8) + (${PATCH})")
|
||
|
||
# 转换为十六进制字符串
|
||
to_hex(${SDK_VERSION_NUMBER_INT} SDK_VERSION_NUMBER)
|
||
# 结果: SDK_VERSION_NUMBER = "0x010A00" (版本 1.10.0)
|
||
|
||
# 包含 TWEAK 的完整版本（32 位编码）
|
||
# 格式: 0xMMNNPPTT (MM=主版本, NN=次版本, PP=补丁, TT=微调)
|
||
math(EXPR SDKVERSION_INT "(${MAJOR} << 24) + (${MINOR} << 16) + (${PATCH} << 8) + (${TWEAK})")
|
||
to_hex(${SDKVERSION_INT} SDKVERSION)
|
||
# 结果: SDKVERSION = "0x010A0000" (版本 1.10.0.0)
|
||
```
|
||
|
||
**编码对比**:
|
||
|
||
| 版本 | SDK_VERSION_NUMBER | SDKVERSION |
|
||
|---------|-------------------|------------|
|
||
| 1.10.0.0 | 0x010A00 (68096) | 0x010A0000 (17432576) |
|
||
| 1.10.1.0 | 0x010A01 (68097) | 0x010A0100 (17432832) |
|
||
| 2.0.0.0 | 0x020000 (131072) | 0x02000000 (33554432) |
|
||
|
||
### 第 4 步: Git 集成（gen_version_h.cmake）
|
||
|
||
**文件**: `cmake/gen_version_h.cmake`
|
||
**执行于**: `cmake/listenai-cmake-config.cmake:132-145`
|
||
|
||
```cmake
|
||
# 尝试获取 git 提交哈希
|
||
find_package(Git QUIET)
|
||
if(GIT_FOUND AND EXISTS ${ARCS_SDK_BASE}/.git)
|
||
execute_process(
|
||
COMMAND ${GIT_EXECUTABLE} describe --abbrev=12 --always
|
||
WORKING_DIRECTORY ${ARCS_SDK_BASE}
|
||
OUTPUT_VARIABLE BUILD_VERSION
|
||
OUTPUT_STRIP_TRAILING_WHITESPACE
|
||
)
|
||
endif()
|
||
|
||
# 从模板生成头文件
|
||
configure_file(${ARCS_SDK_BASE}/sdk_version.h.in ${OUT_FILE})
|
||
```
|
||
|
||
**Git describe 格式**:
|
||
- 有标签时: `v1.10.0-5-g8d2af741d`
|
||
- `v1.10.0`: 最近的标签
|
||
- `5`: 自标签以来的提交数
|
||
- `g8d2af741d`: 提交哈希（12 个字符）
|
||
- 无标签时: `8d2af741d`（仅哈希）
|
||
|
||
### 第 5 步: 头文件生成（arcs_sdk_version.h.in）
|
||
|
||
**模板文件**: `sdk_version.h.in`
|
||
**生成文件**: `build/generated/include/sdk_version.h`
|
||
|
||
**模板内容**:
|
||
|
||
```c
|
||
#ifndef ARCS_SDK_VERSION_H
|
||
#define ARCS_SDK_VERSION_H
|
||
|
||
/* 版本号组件 */
|
||
#define SDK_VERSION_MAJOR @SDK_VERSION_MAJOR@
|
||
#define SDK_VERSION_MINOR @SDK_VERSION_MINOR@
|
||
#define SDK_PATCHLEVEL @SDK_PATCHLEVEL@
|
||
|
||
/* 版本字符串（用于显示） */
|
||
#define SDK_VERSION_STRING @SDK_VERSION_STRING@
|
||
|
||
/* 数值版本编码（用于版本比较） */
|
||
#define SDK_VERSION_CODE @SDK_VERSION_CODE@
|
||
#define SDK_VERSION_NUMBER @SDK_VERSION_NUMBER@
|
||
#define SDKVERSION @SDKVERSION@
|
||
|
||
/* 构建版本信息（Git 提交哈希） */
|
||
#define BUILD_VERSION "@BUILD_VERSION@"
|
||
|
||
/* 版本比较宏 */
|
||
#define SDK_VERSION(a, b, c) (((a) << 16) + ((b) << 8) + (c))
|
||
|
||
#endif /* ARCS_SDK_VERSION_H */
|
||
```
|
||
|
||
**生成的输出**（版本 1.10.0）:
|
||
|
||
```c
|
||
#ifndef ARCS_SDK_VERSION_H
|
||
#define ARCS_SDK_VERSION_H
|
||
|
||
#define SDK_VERSION_MAJOR 1
|
||
#define SDK_VERSION_MINOR 10
|
||
#define SDK_PATCHLEVEL 0
|
||
#define SDK_VERSION_STRING "1.10.0"
|
||
#define SDK_VERSION_CODE 68096
|
||
#define SDK_VERSION_NUMBER 0x010A00
|
||
#define SDKVERSION 0x010A0000
|
||
#define BUILD_VERSION "8d2af741d"
|
||
#define SDK_VERSION(a, b, c) (((a) << 16) + ((b) << 8) + (c))
|
||
|
||
#endif /* ARCS_SDK_VERSION_H */
|
||
```
|
||
|
||
### 第 6 步: 构建执行（listenai-cmake-config.cmake）
|
||
|
||
**文件**: `cmake/listenai-cmake-config.cmake:132-145`
|
||
|
||
```cmake
|
||
# 生成 SDK 版本文件
|
||
execute_process(
|
||
COMMAND ${CMAKE_COMMAND}
|
||
-DARCS_SDK_BASE=${ARCS_SDK_BASE}
|
||
-DOUT_FILE=${CMAKE_BINARY_DIR}/generated/include/sdk_version.h
|
||
-DSDK_VERSION_MAJOR=${SDK_VERSION_MAJOR}
|
||
-DSDK_VERSION_MINOR=${SDK_VERSION_MINOR}
|
||
-DSDK_PATCHLEVEL=${SDK_PATCHLEVEL}
|
||
-DSDK_VERSION_STRING=${SDK_VERSION_STRING}
|
||
-DSDK_VERSION_CODE=${SDK_VERSION_CODE}
|
||
-DSDK_VERSION_NUMBER=${SDK_VERSION_NUMBER}
|
||
-DSDKVERSION=${SDKVERSION}
|
||
-P ${ARCS_SDK_BASE}/cmake/gen_version_h.cmake
|
||
WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 版本变量参考
|
||
|
||
### 完整变量列表
|
||
|
||
| 变量名 | 来源 | 类型 | 示例 | 描述 |
|
||
|--------------|--------|------|---------|-------------|
|
||
| `VERSION_MAJOR` | VERSION 文件 | 整数 | `1` | 主版本号 |
|
||
| `VERSION_MINOR` | VERSION 文件 | 整数 | `10` | 次版本号 |
|
||
| `PATCHLEVEL` | VERSION 文件 | 整数 | `0` | 补丁级别 |
|
||
| `VERSION_TWEAK` | VERSION 文件 | 整数 | `0` | 微调/构建号 |
|
||
| `EXTRAVERSION` | VERSION 文件 | 字符串 | `0` 或 `rc1` | 额外版本后缀 |
|
||
| `PROJECT_VERSION_MAJOR` | 解析后 | 整数 | `1` | 同 VERSION_MAJOR |
|
||
| `PROJECT_VERSION_MINOR` | 解析后 | 整数 | `10` | 同 VERSION_MINOR |
|
||
| `PROJECT_VERSION_PATCH` | 解析后 | 整数 | `0` | 同 PATCHLEVEL |
|
||
| `PROJECT_VERSION_TWEAK` | 解析后 | 整数 | `0` | 同 VERSION_TWEAK |
|
||
| `PROJECT_VERSION_EXTRA` | 解析后 | 字符串 | `0` 或 `rc1` | 同 EXTRAVERSION |
|
||
| `PROJECT_VERSION_WITHOUT_TWEAK` | 计算得出 | 字符串 | `1.10.0` | MAJOR.MINOR.PATCH |
|
||
| `PROJECT_VERSION` | 计算得出 | 字符串 | `1.10.0` 或 `1.10.0.1` | TWEAK 非零时包含 |
|
||
| `PROJECT_VERSION_STR` | 计算得出 | 字符串 | `1.10.0` 或 `1.10.0-rc1` | EXTRA 存在时包含 |
|
||
| `SDK_VERSION_MAJOR` | 导出 | 整数 | `1` | 用于 C 头文件 |
|
||
| `SDK_VERSION_MINOR` | 导出 | 整数 | `10` | 用于 C 头文件 |
|
||
| `SDK_PATCHLEVEL` | 导出 | 整数 | `0` | 用于 C 头文件 |
|
||
| `SDK_VERSION_STRING` | 导出 | 带引号字符串 | `"1.10.0"` | 用于 C 头文件（带引号） |
|
||
| `SDK_VERSION_NUMBER_INT` | 计算得出 | 整数 | `68096` | 十进制: (1<<16)+(10<<8)+0 |
|
||
| `SDK_VERSION_NUMBER` | 计算得出 | 十六进制字符串 | `0x010A00` | 十六进制编码（24 位） |
|
||
| `SDKVERSION_INT` | 计算得出 | 整数 | `17432576` | 包含 TWEAK 的十进制 |
|
||
| `SDKVERSION` | 计算得出 | 十六进制字符串 | `0x010A0000` | 十六进制编码（32 位） |
|
||
| `BUILD_VERSION` | Git | 字符串 | `8d2af741d` | Git 提交哈希 |
|
||
| `SDK_VERSION_CODE` | 别名 | 整数 | `68096` | 同 SDK_VERSION_NUMBER_INT |
|
||
|
||
### 变量使用场景
|
||
|
||
| 场景 | 使用的变量 |
|
||
|---------|---------------|
|
||
| CMake 构建消息 | `PROJECT_VERSION_STR` |
|
||
| C/C++ 版本检查 | `SDK_VERSION_NUMBER`, `SDKVERSION` |
|
||
| 显示给用户 | `SDK_VERSION_STRING`, `BUILD_VERSION` |
|
||
| 版本比较 | `SDK_VERSION_MAJOR/MINOR/PATCHLEVEL` |
|
||
| 宏计算 | `SDK_VERSION(a,b,c)` 宏 |
|
||
|
||
---
|
||
|
||
## 构建集成
|
||
|
||
### CMake 包含链
|
||
|
||
```
|
||
listenai-cmake-config.cmake (主配置)
|
||
├─> cmake/hex.cmake (十六进制工具)
|
||
├─> cmake/version.cmake (版本解析)
|
||
└─> cmake/gen_version_h.cmake (头文件生成)
|
||
```
|
||
|
||
### 构建时执行顺序
|
||
|
||
1. **配置阶段**:
|
||
- 读取 `VERSION` 文件
|
||
- 解析版本组件
|
||
- 设置所有版本变量
|
||
- 计算十六进制编码
|
||
|
||
2. **版本头文件生成**:
|
||
- 获取 Git 哈希（如果在 Git 仓库中）
|
||
- 生成 `sdk_version.h`
|
||
|
||
3. **编译阶段**:
|
||
- C/C++ 文件包含 `sdk_version.h`
|
||
- 编译时可使用版本宏
|
||
|
||
### 控制台输出示例
|
||
|
||
构建时会看到:
|
||
|
||
```
|
||
-- arcs_sdk: 1.10.0 (/path/to/arcs-sdk)
|
||
```
|
||
|
||
这来自 `cmake/version.cmake:65`:
|
||
|
||
```cmake
|
||
if(NOT NO_PRINT_VERSION)
|
||
message(STATUS "arcs_sdk: ${PROJECT_VERSION_STR} (${ARCS_SDK_BASE})")
|
||
endif()
|
||
```
|
||
|
||
---
|
||
|
||
## 版本检查机制
|
||
|
||
### C 代码版本检查
|
||
|
||
应用程序可以在编译时检查版本:
|
||
|
||
```c
|
||
#include "sdk_version.h"
|
||
|
||
#if SDK_VERSION_NUMBER < SDK_VERSION(1, 9, 0)
|
||
#error "此代码需要 SDK 1.9.0 或更高版本"
|
||
#endif
|
||
|
||
// 运行时检查
|
||
if (SDK_VERSION_NUMBER < SDK_VERSION(1, 10, 0)) {
|
||
printf("警告: SDK 版本 %s 低于推荐的 1.10.0\n",
|
||
SDK_VERSION_STRING);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### 启动横幅（boot_banner）
|
||
|
||
**文件**: `startup/arcs/sysmain.c`
|
||
|
||
```c
|
||
#include "sdk_version.h"
|
||
|
||
#if CONFIG_SYSLOG_BANNER
|
||
__attribute__((weak)) void boot_banner(void)
|
||
{
|
||
printf("\n********Arcs SDK %s @ %s********\n",
|
||
SDK_VERSION_STRING, BUILD_VERSION);
|
||
printf("Running on hart-id: %ld\n", (unsigned long)__get_hart_id());
|
||
}
|
||
#endif
|
||
```
|
||
|
||
**输出示例**:
|
||
```
|
||
********Arcs SDK "1.10.0" @ 8d2af741d********
|
||
Running on hart-id: 0
|
||
```
|
||
|
||
### 版本号比较
|
||
|
||
```c
|
||
#include "sdk_version.h"
|
||
|
||
void check_sdk_version(void) {
|
||
// 方法 1: 使用宏比较
|
||
#if SDK_VERSION_NUMBER >= SDK_VERSION(1, 10, 0)
|
||
printf("SDK 版本满足要求\n");
|
||
#else
|
||
#error "需要 SDK 1.10.0 或更高版本"
|
||
#endif
|
||
|
||
// 方法 2: 运行时比较
|
||
if (SDK_VERSION_CODE >= SDK_VERSION(1, 10, 0)) {
|
||
printf("当前 SDK 版本: %s\n", SDK_VERSION_STRING);
|
||
printf("构建版本: %s\n", BUILD_VERSION);
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 修改版本号
|
||
|
||
### 发布新版本
|
||
|
||
1. 编辑 `VERSION` 文件:
|
||
```
|
||
VERSION_MAJOR = 1
|
||
VERSION_MINOR = 11
|
||
PATCHLEVEL = 0
|
||
VERSION_TWEAK = 0
|
||
EXTRAVERSION = 0
|
||
```
|
||
|
||
2. 重新配置构建:
|
||
```bash
|
||
cd build
|
||
cmake ..
|
||
```
|
||
|
||
3. 验证版本:
|
||
```bash
|
||
# 查看生成的头文件
|
||
cat build/generated/include/sdk_version.h
|
||
```
|
||
|
||
### 预发布版本
|
||
|
||
对于 rc1 版本:
|
||
```
|
||
VERSION_MAJOR = 1
|
||
VERSION_MINOR = 11
|
||
PATCHLEVEL = 0
|
||
VERSION_TWEAK = 0
|
||
EXTRAVERSION = rc1
|
||
```
|
||
|
||
生成的版本字符串: `"1.11.0-rc1"`
|
||
|
||
---
|
||
|
||
## 故障排查
|
||
|
||
### 常见问题
|
||
|
||
| 问题 | 原因 | 解决方案 |
|
||
|---------|-------|----------|
|
||
| 版本显示为 0.0.0 | VERSION 文件未找到或格式错误 | 检查 VERSION 文件路径和格式 |
|
||
| 十六进制版本为 0x0 | hex.cmake 未包含 | 验证在使用前 `include(hex.cmake)` |
|
||
| Git 哈希为空 | 不是 git 仓库或未安装 git | 正常行为，BUILD_VERSION 将为 "unknown" |
|
||
| 头文件未重新生成 | CMake 缓存问题 | 删除构建目录并重新配置 |
|
||
|
||
### 调试版本变量
|
||
|
||
在 `version.cmake` 中添加以下内容用于调试:
|
||
|
||
```cmake
|
||
message(STATUS "--- 版本调试信息 ---")
|
||
message(STATUS "PROJECT_VERSION: ${PROJECT_VERSION}")
|
||
message(STATUS "SDK_VERSION_STRING: ${SDK_VERSION_STRING}")
|
||
message(STATUS "SDK_VERSION_NUMBER: ${SDK_VERSION_NUMBER}")
|
||
message(STATUS "SDKVERSION: ${SDKVERSION}")
|
||
message(STATUS "BUILD_VERSION: ${BUILD_VERSION}")
|
||
message(STATUS "-------------------------")
|
||
```
|
||
|
||
---
|
||
|
||
## 文件快速参考
|
||
|
||
| 文件 | 目的 | 何时修改 |
|
||
|------|---------|---------------|
|
||
| `VERSION` | 定义版本号 | 每次发布 |
|
||
| `cmake/version.cmake` | 解析和设置变量 | 添加新版本格式时 |
|
||
| `cmake/hex.cmake` | 十六进制转换工具 | 很少（稳定工具） |
|
||
| `cmake/gen_version_h.cmake` | 生成 C 头文件 | 更改 git 集成时 |
|
||
| `sdk_version.h.in` | C 头文件模板 | 添加新 C 宏时 |
|
||
| `cmake/listenai-cmake-config.cmake` | 集成版本管理 | 更改构建流程时 |
|
||
| `startup/arcs/sysmain.c` | 显示启动横幅 | 更改显示格式时 |
|
||
|
||
---
|
||
|
||
## 附录
|
||
|
||
### 相关文件
|
||
- 版本定义: [VERSION](VERSION)
|
||
- 版本解析: [cmake/version.cmake](cmake/version.cmake)
|
||
- 头文件模板: [sdk_version.h.in](sdk_version.h.in)
|
||
- 头文件生成: [cmake/gen_version_h.cmake](cmake/gen_version_h.cmake)
|
||
|
||
### 文档信息
|
||
- **文档版本**: 1.0
|
||
- **SDK 版本**: ARCS SDK v1.10.0
|
||
- **最后更新**: 2025-12-01
|