平台	目标
windows	simulator

演示 xt-cli v1.2.0 工程版本追踪与管理系统（ xt_deps.jsonc + xt_vers.jsonc ）。

预期行为

核心概念

文件	角色	编辑者	纳入版本控制
xt_deps.jsonc	用户依赖声明（可选）	手动	是
xt_vers.jsonc	机器版本追踪（核心）	xt-cli 自动	是

xt_deps.jsonc 的 deps_configs 段控制默认行为（track / on_version_fail / on_target_fail），优先级高于 xt_conf.jsonc。

演示列表

本示例通过 12 个场景覆盖版本管理的全部功能：

场景	说明	关键知识点
1. 首次编译	无 xt_deps，自动生成 xt_vers	纯追踪模式、自动记录
2. 再次编译	版本一致，静默通过	无变化不写盘
3. 版本不匹配	commit 变化时警告	纯追踪模式的固定警告
4. 精确 pin + on_fail	xt_deps 约束检查	require、on_fail error
5. targets 约束	限制可编译的 target	targets require、排除语法
6. 发布模式	release + dirty 检查	release 字段、–dirty 标志
7. 全局配置	统一管理默认行为	xt config deps.*
8. 跳过追踪	临时或永久停用版本追踪	–no-track、deps.track config
9. 严格模式	一键升级所有约束为 error	–strict 标志
10. 固定版本	批量更新 require 为当前 HEAD	xt deps –update-deps-require
11. 目录哈希	非 git 目录的完整性校验	自动检测、SHA-256
12. 同步依赖	编译前 checkout 仓库到 require 版本	–sync-deps、CI 集成

场景 1：首次编译（纯追踪模式）

没有 xt_deps.jsonc，xt build 后自动生成 xt_vers.jsonc。

# 进入示例工程
cd examples\build_system\deps_demo
 
# 确保没有 xt_deps.jsonc 和 xt_vers.jsonc
del xt_deps.jsonc xt_vers.jsonc -ErrorAction SilentlyContinue
 
# 首次构建
xt build
 
# 产物：xt_vers.jsonc 自动生成
cat xt_vers.jsonc

xt_vers.jsonc 内容示例：

{
  "config_version": 1,
  "xt-sdk": {
    "version": "b29e8fd"
  },
  "platforms": {
    "windows": {
      "version": "b29e8fd",
      "targets": ["simulator"]
    }
  }
}

要点：全部条目用对象格式。targets 记录编译成功的 target。components 为空时不写。

控制台输出：

Info: xt-sdk: first time tracking (commit: b29e8fd)

Info: windows: first time tracking (commit: b29e8fd)

** 要点 ** ：windows 平台无独立 git 仓库，version 跟随 xt-sdk。其他平台（lm620/quectel）各自记录独立仓库的 commit。

场景 2：再次编译（版本一致）

再次编译，仓库无变化，xt_vers.jsonc ** 不写盘 ** （mtime 不变）。

xt build

# 静默通过，无任何输出版本信息

** 要点 ** ：写入前比较现有内容，无变化不写盘。避免 git 噪声。

场景 3：版本不匹配（纯追踪模式警告）

切换到其他 SDK commit 后编译，版本与 xt_vers 记录不一致。

# 切换到其他 commit（模拟同事更新了 SDK）
cd <sdk_dir>
git checkout <other_commit>
 
# 回到工程编译
cd examples\build_system\deps_demo
xt build

控制台输出（ANSI 黄色）：

────────────────────────── WARNING ──────────────────────────
xt-sdk: commit changed since last recorded build.
  Recorded: b29e8fd
  Current:  c9e1234
───────────────────────────────────────────────────────────

** 要点 ** ：纯追踪模式下（无 require），commit 变化固定警告，不受 on_fail 控制。警告后继续编译。

场景 4：精确 pin + on_fail error

创建 xt_deps.jsonc，要求强制匹配指定 commit。

# 创建 xt_deps.jsonc（使用本目录提供的模板）
copy xt_deps.jsonc.example xt_deps.jsonc
 
# 编辑内容，只保留 xt-sdk 约束：
# {
#   "config_version": 1,
#   "xt-sdk": {
#     "require": "00000000",
#     "on_fail": "error"
#   }
# }
 
xt build

当前 commit 不是 00000000，控制台输出（ANSI 红色到 stderr）：

Error: xt-sdk: version constraint not satisfied.
  Required: 00000000
  Current:  b29e8fd

编译中止，返回码 1。

** 操作符支持 ** ：

require	含义
"b8d82d2"	精确匹配（等于 == b8d82d2）
">= c9e1234"	HEAD 是 c9e1234 的后代
"!= b8d82d2, >= c9e1234"	不等于 b8d82d2 且是 c9e1234 的后代

>= <= > < 使用 git merge-base --is-ancestor 判断祖先关系。注意 rebase 后祖先关系可能断裂，出问题改用 == 精确 pin。

场景 5：targets 约束

限制可以编译的 target，防止误编译错误的硬件平台。

{
  "config_version": 1,
  "platforms": {
    "lm620": {
      "targets": ["r4f4", "!= r4f2"]
    }
  }
}

# 编译允许的 target → 通过
xt build --target lm620/r4f4
 
# 编译被排除的 target → 按 on_fail 处理
xt build --target lm620/r4f2
# 输出: Error: lm620: target 'r4f2' not in constraint.
 
# 编译未声明的 target → 按 on_fail 处理（默认 warn）
xt build --target lm620/r4f8

** targets 的完整对象写法 ** （需要覆盖 on_fail 时）：

"quectel": {
  "targets": {
    "require": ["ec600"],
    "on_fail": "error"
  }
}

场景 6：发布模式（release + dirty 检查）

{
  "config_version": 1,
  "release": true,
  "xt-sdk": {
    "require": "b29e8fd"
  }
}

** dirty 仓库 ** （有未提交改动）：

# 正常构建 → 因 release=true 而中止
xt build
# Error: xt-sdk: repository is dirty (release mode).
#   Current:  b29e8fd-dirty
#   Use --dirty to allow.
 
# 显式允许脏编译 → 警告但继续
xt build --dirty
# WARNING: xt-sdk: repository is dirty.

** 行为矩阵 ** ：

release	--dirty	dirty 行为
true	否	警告 + 中止
true	是	警告 + 继续
false/不写	—	警告 + 继续

脏仓库始终警告，--dirty 只控制中不中止。

搭配 --strict 可将 release 外的所有约束升级为 error：

xt build --strict --dirty

# dirty 虽被允许，但其他约束（如版本、targets）全部按 error 处理

场景 7：全局配置 on_fail 默认值

不修改每个条目，统一设置全局默认行为。

# 版本不匹配默认 abort（set 使用 CLI 标志格式）
xt config --deps-on-version-fail error
# deps.on_version_fail set to error (from global config)
 
# target 不匹配默认 abort
xt config --deps-on-target-fail error
 
# 查看当前配置（get/reset 推荐用 dots 格式，也支持 dashes）
xt config --get deps.on_version_fail
# error (from global config)
xt config --get deps-on-version-fail      # dashes 格式也兼容
# error (from global config)
 
# 重置为默认
xt config --reset deps.on_version_fail
# deps.on_version_fail reset (from global config)
 
# 重置后查看，返回默认值
xt config --get deps.on_version_fail
# warn (from default)
 
# 查看所有配置（分区展示 local / global / defaults）
xt config
# --- Local config (D:\project\xt_conf.jsonc) ---
#   (empty)
#
# --- Global config (C:\Users\mao\.xt\xt_conf.jsonc) ---
#   sdk = D:/work/xt-sdk
#   target = windows/simulator
#   deps.on_version_fail = error
#
# --- Defaults ---
#   deps.on_target_fail = warn
#   deps.track = False

条目显式的 on_fail 字段优先级高于全局配置。

** 优先级链 ** ：条目显式值 > xt_deps.jsonc deps_configs 段 > 工程 xt_conf.jsonc > 全局 ~/.xt/xt_conf.jsonc > 默认 "warn"

场景 8：跳过本次追踪

deps.track 默认 false，本示例在 xt_deps.jsonc 的 deps 段显式设为 true。

# 临时跳过 xt_vers 更新（即使追踪已开启）
xt build --no-track
# xt_vers.jsonc 不会被更新
 
# 持久化关闭（修改 xt_deps.jsonc deps_configs.track）
# 或通过 xt_conf.jsonc 覆盖：
xt config --local --deps-track false
xt build
# 也不会更新 xt_vers
 
# 重新开启
xt config --local --deps-track true

--no-track 单次生效。deps.track 优先从 xt_deps.jsonc 的 deps_configs 段读取，未写时走 xt_conf.jsonc，最终默认 false。

场景 9：严格模式

--strict 将所有依赖约束的 on_fail 临时升级为 error，无需逐个修改配置。同时检查工程自身仓库干净（dirty 中止）和所有已追踪仓库干净（除非同时 --dirty）。

# --strict 把所有约束升级为 error，dirty 中止
xt build --strict
# 等价于：所有 on_fail → error + dirty 中止
 
# 允许 dirty 但约束仍是 error
xt build --strict --dirty
# 等价于：所有 on_fail → error，dirty 仅警告

--strict 不影响 release 字段的 dirty 行为（release 仍由 --dirty 控制），但 --strict 本身会独立导致 dirty 中止。

场景 10：固定当前版本

将 xt_deps.jsonc 中所有条目的 require 批量更新为当前 HEAD sha，适合发布前锁定全部依赖。

# 更新全部条目的 require 为当前 HEAD sha
xt deps --update-deps-require
 
# 只更新指定平台
xt deps --update-deps-require=lm620
 
# 更新多个
xt deps --update-deps-require=xt-sdk,lm620,quectel

执行后 xt_deps.jsonc 中对应条目的 require 会被写为当前版本（git sha 或 hash）。已有精确 pin 的条目会被覆盖。

CI 场景推荐用 xt build --sync-deps 编译前自动 checkout 各仓库到 require 版本。

场景 11：目录哈希（非 git 仓库）

本示例自带一个本地组件 components/my_utils/（非 git 仓库），require 写为普通字符串即可自动按哈希校验：

"components": {
  "my_utils": {
    "require": "715804dc",
    "on_fail": "error"
  }
}

也可显式写 {"type": "hash", "val": "715804dc"}，效果相同。显式写 type: "git" 但无 .git 会报错。

组件默认路径为 <project_dir>/components/<name>，无需额外指定 path。

hash_dir 自动读取目录下的 .gitignore，支持 * ? [seq] ** ! 规则。本示例的 .gitignore 排除了 *.o *.obj build/，构建产物不参与哈希。

** 验证哈希检查 ** ：

# 正常编译 → 哈希匹配，静默通过
xt build
 
# 修改组件文件，重新计算哈希
echo "// comment" >> components\my_utils\my_utils.c
xt deps --hash components/my_utils
# 输出新的哈希值
 
# 再次编译 → 哈希不匹配
xt build
# Error: my_utils: version constraint not satisfied.
#   Required: 715804dc
#   Current:  <新的哈希>

** 手动计算哈希 ** ：

xt deps --hash components/my_utils

修改组件后，更新 xt_deps.jsonc 中的 require.val 为新的哈希值即可。

场景 12：同步依赖（–sync-deps）

编译前自动将各仓库 checkout 到 xt_deps.jsonc 要求的版本，适合 CI 环境。

# 编译前自动同步依赖版本
xt build --sync-deps
 
# 即使仓库 dirty 也允许同步
xt build --sync-deps --dirty

行为：遍历 xt_deps.jsonc 条目，git sha 直接 checkout，semver 按 tag 查找，hash 类型跳过。安全规则：dirty 仓库默认中止（--dirty 覆盖），找不到目标报错，已在目标版本跳过。

CI 推荐组合：xt build --sync-deps --strict

# .gitea/workflows/ci.yml
- name: build
  run: xt build --sync-deps --strict --target=lm620/r4f4

xt_vers.jsonc 字段总览

字段	层级	必需	说明
config_version	顶层	是	文件格式版本
xt-sdk	顶层	否	编译时 xt-sdk 版本（对象格式）
platforms	顶层	否	编译到的平台及其版本
components	顶层	否	组件依赖，非空时才写入
version	条目	是	版本字符串（sha / sha-dirty / hash）
targets	条目	否	编译过的 target 列表，编译成功才追加不重复
source	条目	否	来源类型，非默认 git 时写入（如 {"type": "hash"}）

条目值始终为对象 {"version": "..."}。有 targets 或非默认 source 时追加对应字段。

xt_deps.jsonc 字段总览

字段	层级	必需	说明
config_version	顶层	是	文件格式版本，当前为 1
release	顶层	否	发布模式，dirty → 中止（--dirty 覆盖）
xt-sdk	顶层	否	SDK 版本约束
platforms.<name>	条目	否	平台依赖约束
require	条目	否	版本约束（字符串或 {type, val}）
on_fail	条目	否	版本不匹配行为（warn/error/ignore）
targets	条目	否	target 约束（数组或 {require, on_fail}）
path	条目	否	自定义仓库路径
components	顶层	否	组件依赖（预留）

编译和运行

cd examples/build_system/deps_demo

xt --target windows/simulator fullclean build