xt-cli 0.2.2

xt sdk command line tool

xt-cli

xt-cli 是 xt-sdk 的命令行工具，用于简化 xt-sdk 的配置、编译、清理和运行流程。

安装

pip install xt-cli

快速开始

xt config --sdk <sdk-path>
cd <project-dir>
xt build --target <target>

命令

xt-cli 基础命令格式如下：

xt [GLOBAL OPTIONS] TASK [TASK OPTIONS] ...

命令	说明
xt build	编译工程，支持 xt clean build 多 task 组合
xt clean	清理构建产物（xmake clean）
xt fullclean	删除 .xmake / .build 目录
xt config	管理配置，支持 set / get / reset / show
xt deps	管理版本依赖，--update-deps-require 更新 require
xt --version	输出版本号

全局参数

以下参数可用于命令行任意位置：

参数	说明	示例
--target / -t	目标平台路径或名称	windows/simulator、lm620/r4f4
--sdk	SDK 根目录路径	D:/xt-sdk
--toolchain-path	工具链路径	C:/tools/mingw64/bin
--project / -p	工程目录路径	examples/get_started/hello_world
--board	板级名称	e837n_v01、simulator
--dirty	允许脏仓库编译	—
--no-track	跳过本次 xt_vers 更新	—
--strict	严格模式：强制所有约束，dirty 中止	—
--sync-deps	编译前 checkout 各仓库到 xt_deps.jsonc 要求版本	—

配置系统

配置文件 xt_conf.jsonc（JSONC 格式），支持工程级（local）和用户级（~/.xt/ global）二级作用域。优先级：CLI 参数 > 工程配置 > 全局配置 > 默认值。

xt config --sdk D:/xt-sdk                   # 设置 SDK 路径
xt config --target windows/simulator        # 设置默认 target
xt config --platform windows --toolchain-path C:/mingw64/bin
xt config --get sdk                         # 查询
xt config --reset target                    # 重置
xt config                                   # 展示全部配置

Hook 扩展

在工程目录或平台目录下创建 xt_hook.py，定义 handle_<task> 函数即可扩展命令。xt-cli 自动发现并注册，import xt_cli 提供稳定 API：

import xt_cli

def handle_flash(context: xt_cli.BuildContext, global_args, shared_args, self_args, unknown_args):
    """--help: Flash firmware to the device."""
    print(f"flashing {context.target} via {self_args.port}")
    return 0

def add_args_flash(parser):
    parser.add_argument("--port", default="COM1")

xt flash --port COM3           # 自动分发到 handle_flash
xt build                       # 自动触发 before_build / after_build 生命周期

• 调度优先级：工程 hook > 平台 hook
• 支持 before_build / after_build / before_clean / after_clean 等生命周期 hook
• context.run_task("build") 支持 hook 内组合调用内置命令

版本追踪

每次 xt build 自动记录依赖仓库的 git commit 到 xt_vers.jsonc。通过 xt_deps.jsonc 声明版本约束，不匹配时自动警告或中止：

// xt_deps.jsonc
{
  "xt-sdk": { "require": ">= c9e1234" },
  "platforms": {
    "windows": { "require": "b8d82d2", "targets": ["simulator"] }
  }
}

xt build                        # 自动检查约束，通过后编译并记录版本
xt build --strict               # 约束不匹配 → 中止
xt build --dirty                # 允许脏仓库编译
xt build --no-track             # 本次跳过版本记录
xt build --sync-deps            # 编译前 checkout 各仓库到 require 版本
xt deps --update-deps-require   # 将当前版本写回 xt_deps.jsonc