hook_demo

平台	目标
windows	simulator

演示 xt-cli v1.1.5 的 hook 扩展机制，覆盖规范中的所有用法。

预期行为

调用优先级

工程 hook  >  平台 hook  >  xt-cli 内置行为

1. xt-cli 先查找 工程 hook （工程根目录下的 xt_hook.py ）
2. 工程 hook 未处理时，查找 平台 hook （ platforms/<platform>/xt_hook.py ）
3. 均未处理时，走 xt-cli 内置行为（build/clean/run 走 xmake，其他 task 报错）

演示列表

本示例通过 7 个演示覆盖 hook 规范中的所有用法：

演示	命令	说明	hook 来源
1. 特定 task + 专属 option	xt flash --port COM3	handle_<task> 接口， add_args_flash 注册 --port ，通过 self_args.port 取值	平台 hook
2. BuildContext 字段	xt info	读取 context 的所有字段	平台 hook
3. 同名 task 优先级	xt greet	平台和工程都定义了 handle_greet ，由工程 hook 处理	工程 hook
4. 工程独有命令	xt deploy --output dist	工程 hook 定义此 task，由工程 hook 处理	工程 hook
5. 通用 fallback	xt unknown_task --foo bar	handle() 通用 fallback，返回 None 交回 xt-cli	工程 hook
6. 组合命令	xt project_release	context.run_task 组合多个 task	工程 hook
7. 生命周期 hook	xt build （自动触发）	before_build / after_build 在内置命令前后自动调用	工程 + 平台 hook

使用示例

# 设置默认 target
xt config --target windows/simulator
 
# 进入示例工程目录
cd examples\build_system\hook_demo
 
# --- 内置命令 ---
# 构建（hook 未拦截，走 xt-cli 内置 xmake 流程）
xt build
 
# --- 演示 1：特定 task 函数 + 解析 args ---
# 平台 hook 的 handle_flash 处理，--port 通过 self_args.port 获取
xt flash --port COM3
# 输出:
# [platform hook] flashing windows/simulator via COM3
# [platform hook]   target_path: ...\platforms\windows\simulator
# [platform hook]   project_dir: ...\examples\build_system\hook_demo
 
# --- 演示 2：BuildContext 字段 ---
# 平台 hook 的 handle_info，打印 context 所有字段
xt info
# 输出:
# [platform hook] --- BuildContext ---
# [platform hook]   sdk_dir:        ...\xt-sdk
# [platform hook]   project_dir:    ...\examples\build_system\hook_demo
# [platform hook]   target:         windows/simulator
# [platform hook]   target_path:    ...\platforms\windows\simulator
# [platform hook]   platform_name:  windows
# [platform hook]   toolchain_path: C:\tools\mingw64\bin
# [platform hook]   debug_enabled:  False
 
# --- 演示 3：同名 task 优先级 ---
# 平台 hook 和工程 hook 都定义了 handle_greet
# 由于工程 hook > 平台 hook，由工程 hook 处理
xt greet
# 输出:
# [project hook] greet from ...\examples\build_system\hook_demo
 
# --- 演示 4：工程独有命令 ---
# 平台 hook 没有 handle_deploy，由工程 hook 处理
xt deploy --output dist
# 输出:
# [project hook] deploying from ...\examples\build_system\hook_demo
# [project hook]   target: windows/simulator
# [project hook]   output: dist
 
# --- 演示 5：通用 fallback ---
# 两个 hook 都没有 handle_unknown_task，走到工程 hook 的 handle() fallback
# handle() 返回 None，xt-cli 输出 "Unknown task: unknown_task"
xt unknown_task --foo bar
# 输出:
# [project hook] unhandled task: unknown_task, args: ['--foo', 'bar']
# Unknown task: unknown_task
 
# --- 演示 6：组合命令 ---
# 工程 hook 的 handle_project_release，通过 run_task 组合多个步骤
xt project_release
# 输出:
# [project hook] project_release: step 1 - build
# [project hook] project_release: step 2 - greet
# [project hook] greet from ...\examples\build_system\hook_demo
 
# --- 演示 7：生命周期 hook ---
# before_build 在 xmake 之前自动触发（工程 hook）
# after_build 在 xmake 之后自动触发（工程 hook）
xt build
# 输出:
# [project hook] before_build: preparing...
# ... (xmake build output) ...
# [project hook] after_build: build completed for windows/simulator

编译和运行

cd examples/build_system/hook_demo
xt --target windows/simulator build