Metadata-Version: 2.4
Name: xt-cli
Version: 0.2.2
Summary: xt sdk command line tool
Author: xt-sdk
License-Expression: Apache-2.0
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: json5<1,>=0.10
Dynamic: license-file

# xt-cli

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

## 安装

```powershell
pip install xt-cli
```

## 快速开始

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

## 命令

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

```text
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 参数 > 工程配置 > 全局配置 > 默认值。

```powershell
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：

```python
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")
```

```powershell
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` 声明版本约束，不匹配时自动警告或中止：

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

```powershell
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
```
