XT-SDK 快速入门

XT-SDK 是一套面向嵌入式/跨平台应用的构建与组件组织框架，用来把应用工程、平台适配层和公共组件解耦。

xt-cli

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

安装

# 安装 xt-cli（新用户）
pip install xt-cli
 
# v1.0.1 用户升级 xt-cli
pip uninstall xt-cli
pip install xt-cli

详细变更记录见 发布说明 （RELEASE.md）。

首次配置

目前还没有一键安装功能，首次使用需要先手动配置。

cd <SDK_PATH>
 
# 设置 sdk 路径，支持使用相对路径，例如当前目录
xt config --sdk "."
 
# 设置 windows 平台工具链路径
xt config --platform "windows" --toolchain-path "C:\tools\winlibs-x86_64-posix-seh-gcc-15.2.0-mingw-w64ucrt-13.0.0-r1\mingw64\bin"
 
# 设置 lm620 平台工具链路径
xt config --platform "lm620" --toolchain-path "D:\work\pt\lm620\ict-build\ZCnuclei\win\bin"
 
# 设置 quectel 平台工具链路径
xt config --platform "quectel" --toolchain-path "D:\tools\ql-cross-tool\win32\owtoolchain\gcc-arm-none-eabi\bin"

编译和运行

windows 平台

# 设置默认 target 为 windows/simulator
xt config --target windows/simulator
 
# 进入示例工程目录
cd examples\build_system\app_with_components
 
# 清理后重新编译
xt fullclean build
 
# 运行（不再是内置命令，改为通过 Windows 平台 hook 实现）
xt run

lm620 平台

# 设置默认 target 为 lm620/r4f4
xt config --target lm620/r4f4
 
# 进入示例工程目录
cd examples\build_system\app_with_components
 
# 清理后重新编译
xt fullclean build
 
# 编译完后固件输出到 examples\build_system\app_with_components\.build\lm620_r4f4\bin

quectel 平台

# 设置默认 target 为 quectel/800akcn91lcp1
xt config --target quectel/800akcn91lcp1
 
# 进入示例工程目录
cd examples\build_system\app_with_components
 
# 清理后重新编译
xt fullclean build
 
# 编译完后固件输出到 examples\build_system\app_with_components\.build\quectel_800akcn91lcp1\output

板级配置

部分示例依赖板级配置（xt_board（板级配置） 组件），编译时必须指定 --board 参数：

# lm620 平台使用 e837n_v01 板子
xt --board e837n_v01 fullclean build
 
# windows/linux 模拟器使用 simulator 板子
xt --board simulator --target windows/simulator fullclean build

也可持久化到配置：

xt config --board e837n_v01

不指定 --board 时，xt_board（板级配置） 组件会报错提示设置 XT_SDK_BOARD 环境变量。

程序入口

XT-SDK 应用的入口函数为 xt_main，由 RTOS 线程调用：

int xt_main(void)
{
    xt_hal_core_setup();         // 1. 初始化核心硬件
    xt_log_setup(0, 0, 0, 0);    // 2. 初始化日志
    xt_task_setup();             // 3. 初始化协程任务框架
 
    // 4. 启动任务、注册事件、启动定时器 ...
 
    // 5. 主循环
    uint32_t timeout = 0;
    while (1) {
        xt_event_pre_handler_os_ext(timeout);
        do {
            xt_event_handler();
            timeout = xt_timer_handler();
        } while (xt_event_ready());
    }
    return 0;
}

头文件包含规则

需要的功能	包含的头文件
基础类型 + HAL + 功能组件	#include "xtiny.h"
协程任务框架	#include "xt_task.h"
事件系统	#include "xt_event.h"
系统事件定义（XT_EVENT_USER_START）	#include "xt_sys_event.h"
软件定时器	#include "xt_timer.h"
RTOS 接口（osDelay 等）	#include "cmsis_os2.h"
Ring Buffer	#include "xt_rb.h"
Socket	#include "xt_socket.h"
VFS	#include "xt_vfs.h"

xtiny.h 是总头文件，已包含 HAL、Log、FS、Mobile、OTA、Audio 等常用模块。核心框架（Task/Event/Timer）需要单独包含。

（不推荐使用，仅调试用途）支持原生 xmake 编译

windows

cd <SDK_PATH>
# 首次需要输入工具链可执行文件路径，如 C:\tools\winlibs-x86_64-posix-seh-gcc-15.2.0-mingw-w64ucrt-13.0.0-r1\mingw64\bin
. .\export.ps1 windows/simulator
# 需要显式指定工程路径
$env:XT_SDK_PROJECT_PATH = "$env:XT_SDK_ROOT\examples\build_system\app_with_components"
# 有些工程要指定板子
$env:XT_SDK_BOARD = "simulator"
# 目前必须切到示例目录才能将临时文件正确输出到 XT_SDK_PROJECT_PATH/.build
cd examples\build_system\app_with_components
xmake build -F "$env:XT_SDK_ROOT\xmake.lua"
# 目前 platforms\windows\xmake.lua 的 app 目标已经设置 set_default(true), 
# 下面的 app 参数不是必须的
xmake run -F "$env:XT_SDK_ROOT\xmake.lua" app

lm620

cd <SDK_PATH>
# 首次需要输入工具链可执行文件路径，如 D:\work\pt\lm620\ict-build\ZCnuclei\win\bin
. .\export.ps1 lm620/r4f4
# 需要显式指定工程路径
$env:XT_SDK_PROJECT_PATH = "$env:XT_SDK_ROOT\examples\build_system\app_with_components"
# 有些工程要指定板子
$env:XT_SDK_BOARD = "e837n_v01"
# 目前必须切到示例目录才能将临时文件正确输出到 XT_SDK_PROJECT_PATH/.build
cd examples\build_system\app_with_components
xmake build -F "$env:XT_SDK_ROOT\xmake.lua"
# 编译完后固件输出到 $env:XT_SDK_ROOT\examples\build_system\app_with_components\.build\lm620_r4f4\bin
xmake build -F xmake.lua