UniRTOS CLI 用户使用手册
版本: unirtos-cli v1.0.14+
适用平台: Windows / Linux / macOS(目前编译工具链仅支持 Windows 系统)
1. 前提条件
在使用 unirtos-cli 之前,请确保以下工具已安装并配置到系统 PATH:
| 工具 | 说明 | 最低版本 |
|---|---|---|
| Python | 运行 CLI 工具本身 | 3.9+ |
| Git | 拉取 SDK 与库源码 | 2.20+ |
| unirtos 工具链 | 提供 unirtos 命令用于编译 |
1.0.5+ |
验证命令:
python --version # 或 python3 --version
git --version
unirtos --version
2. 安装
pip install unirtos-cli
安装完成后,unirtos-cli 命令即可在终端中全局使用。
升级到最新版:
pip install --upgrade unirtos-cli
3. 快速开始
# 1. 创建并进入项目目录
unirtos-cli new unirtos-app
cd unirtos-app
# 2. 编辑 env_config.json(见第 4 节)
# 3. 拉取 SDK 与依赖库
unirtos-cli env-setup
# 4. 编译
unirtos-cli build
说明:env-setup 执行完成后,会在 App 根目录自动生成 <app-name>.code-workspace,可一键在 VSCode 打开 App、SDK 与依赖库代码。
编译产物默认输出到项目目录下的 qos_build/release/<version>/。
4. 配置文件详解 (env_config.json)
env_config.json 是项目根目录下的核心配置文件,由 new 命令自动生成模板,用户需在其中填写模块名称等信息。针对基于模板创建项目的场景,sdk.version 会自动写入最新可用 SDK 版本。
使用建议(推荐)
对于绝大多数用户,日常只需要关注并维护以下字段:
build.module:编译模组型号build.version:目标版本号build.jobs:并发编译线程数sdk.version:SDK 版本libraries.list[].name/libraries.list[].version:依赖库名称与版本
其余 Manifest 相关字段(如 sdk.manifest_repo_url、sdk.manifest_repo_branch、libraries.manifest_repo_url、libraries.manifest_repo_branch、demos.manifest_repo_url、demos.manifest_repo_branch)在无私有镜像、内网仓库或特殊分支需求时,建议保持模板默认值,不要修改。
完整示例
{
"unirtos_root": "",
"build": {
"module": "EG800ZCN_LA",
"version": "EG800ZCNLAR01A01_BETA_OCPU_20260513",
"jobs": 8
},
"sdk": {
"version": "1.0.0",
"manifest_repo_url": "https://github.com/unirtos/unirtos-sdk-manifests.git",
"manifest_repo_branch": ""
},
"libraries": {
"manifest_repo_url": "https://github.com/unirtos/unirtos-libs-manifests.git",
"manifest_repo_branch": "",
"list": [
{
"name": "lib-name",
"version": "2.0.0"
}
]
},
"demos": {
"manifest_repo_url": "https://github.com/unirtos/unirtos-demos-manifests.git",
"manifest_repo_branch": ""
}
}
字段说明
顶层字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
unirtos_root |
string | 否 | UniRTOS 全局存储根目录的绝对路径。留空时自动使用默认路径:~/.unirtos(Linux/macOS)或 C:\Users\<用户名>\.unirtos(Windows)。 |
build 对象
控制 unirtos-cli build 的编译行为。所有字段均可被 CLI 参数覆盖。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
module |
string | 是 | SDK 模块/硬件平台名称,例如 EG800ZCN_LA。对应 unirtos make --project 参数。 |
version |
string | 否 | 固件版本字符串,例如 EG800ZCNLAR01A01_BETA_OCPU_20260513。留空时默认使用应用根目录名称。对应 unirtos make --version 参数。 |
jobs |
integer | 否 | 并行编译线程数。省略时默认为 4。可用 -j 参数临时覆盖。 |
sdk 对象
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
version |
string | 是 | 要使用的 SDK 版本号,例如 1.0.0。模板创建场景下会默认写入最新可用版本;env-setup 会将该值映射为 SDK Git 标签 v<version>(如 v1.0.0)进行源码检出并存储。 |
manifest_repo_url |
string | 否 | SDK Manifest 仓库地址。省略时使用官方默认地址。可配置为私有/镜像地址。 |
manifest_repo_branch |
string | 否 | SDK Manifest 仓库分支名。留空或省略时,按优先级自动尝试:main → master;填写后优先使用该分支。 |
libraries 对象
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
manifest_repo_url |
string | 否 | 库 Manifest 仓库地址。省略时使用官方默认地址。 |
manifest_repo_branch |
string | 否 | 库 Manifest 仓库分支名。留空或省略时,按优先级自动尝试:main → master;填写后优先使用该分支。 |
list |
array | 否 | 依赖库列表。每项包含 name(库名)和 version(版本号)两个字段。不需要任何外部库时可省略 list 或置为空数组 []。 |
demos 对象
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
manifest_repo_url |
string | 否 | Demo Manifest 仓库地址。省略时使用官方默认地址。 |
manifest_repo_branch |
string | 否 | Demo Manifest 仓库分支名。留空或省略时,按优先级自动尝试:main → master;填写后优先使用该分支。 |
库列表项
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name |
string | 是 | 库名称,需与 Manifest 仓库中的目录名一致。 |
version |
string | 是 | 库版本号,例如 2.0.0。 |
5. 命令参考
5.1 new — 创建新项目
创建一个新的项目。支持两种模式:
- 模板模式(默认):基于
app-tmpl创建项目。 - Demo 模式(
-r/--from-demo):基于远程同名 demo 仓库创建项目。
unirtos-cli new [-r] <project-name> [-v <version>] [-d <project-dir>] [-f]
| 参数 | 默认值 | 说明 |
|---|---|---|
project-name |
必填 | 项目名称(仅名称,不允许路径分隔符)。 |
-r, --from-demo |
关闭 | 从远程 demo 创建项目。 |
-v, --version |
省略 | 指定远程 demo 版本(支持 1.0.0 或 v1.0.0)。仅可与 -r 同时使用;省略时自动选择最新版本。 |
-d, --project-dir |
.(当前目录) |
项目基目录。最终目录为 <project-dir>/<project-name>。 |
-f, --force |
关闭 | 强制更新 <unirtos_root>/demos/manifests 后再选 demo。仅可与 -r 同时使用。 |
行为说明:
- 模板模式(不带
-r)创建项目时,会自动将新项目env_config.json中的sdk.version写为最新可用 SDK 版本。
示例:
# 1) 基于模板创建(默认)
unirtos-cli new unirtos-app
# 2) 指定项目基目录
unirtos-cli new unirtos-app -d /path/to/workspace
# 3) 基于远程 demo 创建(按 demo 名称匹配)
unirtos-cli new -r demo_a
# 4) 基于远程 demo 创建(强制刷新本地缓存的 demo 列表信息)
unirtos-cli new -r demo_a -d /path/to/workspace -f
# 5) 基于远程 demo 指定版本创建
unirtos-cli new -r demo_a -v 1.0.0
5.2 env-setup — 拉取环境
根据 env_config.json 的配置,拉取指定版本的 SDK 和所有依赖库到本地存储目录。
unirtos-cli env-setup [-d <project-dir>]
| 参数 | 默认值 | 说明 |
|---|---|---|
-d, --project-dir |
.(当前目录) |
包含 env_config.json 的项目目录。 |
示例:
cd unirtos-app
unirtos-cli env-setup
5.3 build — 编译项目
调用 UniRTOS 工具链的 unirtos make 命令,以 SDK 驱动 模式编译当前外部应用。
unirtos-cli build [-d <project-dir>] [-j <jobs>] [-m <module>] [-v <version>]
| 参数 | 默认值 | 优先级 | 说明 |
|---|---|---|---|
-d, --project-dir |
. |
— | 项目目录。 |
-j, --jobs |
4 |
CLI > env_config.build.jobs > 4 |
并行编译线程数。 |
-m, --module |
env_config.build.module |
CLI > env_config.build.module |
模块名,例如 EG800ZCN_LA。 |
-v, --version |
应用根目录名称 | CLI > env_config.build.version > 应用根目录名称 |
固件版本字符串。 |
编译产物位置:
<project-dir>/qos_build/release/<version>/
示例:
# 使用 env_config.json 中的默认配置编译
unirtos-cli build
# 指定模块和线程数(覆盖配置文件)
unirtos-cli build --module EG800ZCN_LA --jobs 8
# 指定完整版本字符串
unirtos-cli build -m EG800ZCN_LA -v EG800ZCNLAR01A01_BETA_OCPU_20260513
5.4 clean — 清理构建产物
删除项目目录下的所有编译产物(qos_build/ 目录内容)。
unirtos-cli clean [-d <project-dir>]
| 参数 | 默认值 | 说明 |
|---|---|---|
-d, --project-dir |
. |
项目目录。 |
示例:
unirtos-cli clean
5.5 menuconfig — 打开配置菜单
内核功能开关配置界面。
unirtos-cli menuconfig [-d <project-dir>]
| 参数 | 默认值 | 说明 |
|---|---|---|
-d, --project-dir |
.(当前目录) |
起始目录(向上查找 env_config.json 所在目录)。 |
示例:
# 在当前项目目录执行
unirtos-cli menuconfig
# 指定项目目录执行
unirtos-cli menuconfig -d /path/to/project
5.6 version — 查看 CLI 版本
输出当前安装的 unirtos-cli 版本号。
unirtos-cli version
示例输出:
unirtos-cli v1.0.14
5.7 ls-sdk — 查看 SDK 版本列表
列出本地已安装或远程可用的 SDK 版本。
unirtos-cli ls-sdk [-r] [-f] [-j] [-d <project-dir>]
| 参数 | 说明 |
|---|---|
-l, --local |
查看本地已安装版本(默认行为,可省略)。 |
-r, --remote |
查看远程可用版本(从 Manifest 仓库读取)。 |
-f, --force |
强制刷新本地 Manifest 仓库缓存(默认 1 小时内不重复拉取)。仅在 -r 时有效。 |
-j, --json-output |
以 JSON 格式输出结果,便于脚本集成。 |
-d, --project-dir |
起始目录。命令会从该目录向上查找 env_config.json;若找到则使用其中的 unirtos_root,否则回退到 ~/.unirtos。默认为当前目录。 |
示例:
# 查看本地已安装的 SDK 版本
unirtos-cli ls-sdk
# 输出:
# Installed SDK versions:
# - 1.0
# - 1.1
# 查看远程可用的 SDK 版本(使用缓存)
unirtos-cli ls-sdk -r
# 强制刷新后查看远程版本
unirtos-cli ls-sdk -r -f
# 以 JSON 格式输出远程版本列表
unirtos-cli ls-sdk -r -j
# 输出:
# {
# "success": true,
# "message": "Remote SDK versions fetched successfully",
# "type": "sdk-remote",
# "data": ["1.0", "1.1", "1.2"]
# }
缓存机制说明: 远程版本查询会在本地缓存 Manifest 仓库(位于 <unirtos_root>/sdk/manifests/,若未命中应用配置则为 ~/.unirtos/sdk/manifests/)。两次查询间隔不足 1 小时时自动使用缓存,不重复联网。使用 -f 可强制立即更新。
5.8 ls-libs — 查看库版本列表
列出本地已安装或远程可用的依赖库及其版本。
unirtos-cli ls-libs [-r] [-f] [-j] [-d <project-dir>]
参数与 ls-sdk 完全一致,含义相同。
-d/--project-dir 同样从该目录向上查找 env_config.json;若找到则使用其中的 unirtos_root,否则回退到 ~/.unirtos。
示例:
# 查看本地已安装的库
unirtos-cli ls-libs
# 输出:
# Installed libraries:
# component_a: 1.0.0, 2.0.0
# component_b: 1.2.0
# 查看远程可用库及版本(JSON 格式)
unirtos-cli ls-libs -r -j
# 输出:
# {
# "success": true,
# "message": "Remote library versions fetched successfully",
# "type": "lib-remote",
# "data": {
# "component_a": ["1.0.0", "2.0.0"],
# "component_b": ["1.2.0"]
# }
# }
5.9 ls-demos — 查看 Demo 版本列表
列出远程 Demo 及其版本。
unirtos-cli ls-demos [-f] [-j] [-d <project-dir>]
参数说明:
| 参数 | 说明 |
|---|---|
-f, --force |
强制更新 <unirtos_root>/demos/manifests(忽略 1 小时更新间隔)。 |
-j, --json-output |
JSON 输出。 |
-d, --project-dir |
起始目录。命令会从该目录向上查找 env_config.json;若找到则使用其中的 unirtos_root,否则回退到 ~/.unirtos。 |
示例:
# 查看 demo 版本(默认读取本地 manifests 缓存;必要时按策略更新)
unirtos-cli ls-demos
# 输出:
# Remote demos:
# demo_a: 1.0.0
# demo_b: 2.0.0
# 强制更新 manifests 后输出 JSON
unirtos-cli ls-demos -f -j
# 输出:
# {
# "success": true,
# "message": "Demo versions fetched successfully",
# "type": "demo-remote",
# "data": {
# "demo_a": ["1.0.0"],
# "demo_b": ["2.0.0"]
# }
# }
6. 基于模板的应用接入与编译配置
本节用于说明:执行 new 生成模板后,如何按需调整应用侧 CMakeLists.txt,确保应用可被 SDK 正确识别并完成编译。
6.1 CMakeLists.txt 最小接入要求
模板生成的 CMakeLists.txt 已满足外部应用编译契约,通常只需关注以下 2 点:
- 将你的源码目录加入
target_sources(...)。 - 将你的头文件目录加入
target_include_directories(...)。
最常见的自定义方式是扩展源码目录。例如新增 components/ 目录后:
file(GLOB_RECURSE APP_SRC
${CMAKE_CURRENT_SOURCE_DIR}/main/src/*.c
${CMAKE_CURRENT_SOURCE_DIR}/components/**/*.c
)
target_sources(${target} PRIVATE ${APP_SRC})
target_include_directories(${target} PUBLIC
${CMAKE_CURRENT_SOURCE_DIR}/main/inc
${CMAKE_CURRENT_SOURCE_DIR}/components
)
如果你新增的是子模块(子目录中也有 CMakeLists.txt),可以在顶层应用 CMakeLists.txt 中按需启用:
add_subdirectory_if_exist(app_components)
6.2 推荐落地步骤
# 1) 初始化模板项目
unirtos-cli new unirtos-app
cd unirtos-app
# 2) 修改 CMakeLists.txt:补充你的源码/头文件路径
# 3) 拉取环境
unirtos-cli env-setup
# 4) 按需配置 menuconfig
unirtos-cli menuconfig
# 5) 编译验证
unirtos-cli build
6.3 常见失败原因
CMakeLists.txt未将新增.c文件加入target_sources,导致链接缺符号。- 头文件目录未加入
target_include_directories,导致编译找不到头文件。 - 依赖的底层组件未通过 menuconfig 进行正确配置,导致相关 API 或组件不可用。
7. 本地存储目录结构
所有 SDK 与库源码统一存储在 unirtos_root(默认 ~/.unirtos/)下,结构如下:
~/.unirtos/
├── sdk/
│ ├── manifests/ ← SDK Manifest Git 仓库(ls-sdk -r 与 env-setup 共享)
│ │ ├── .git/
│ │ ├── v1.0.0/
│ │ │ └── default.xml ← v1.0.0 版本的 project 列表
│ │ └── v1.0.1/
│ │ └── default.xml
│ ├── v1.0.0/
│ │ ├── version.txt ← 内容为 "1.0.0",用于版本匹配校验
│ │ └── ... ← SDK 源码(由 manifest 定义的各 Git 仓库)
│ └── v1.0.1/
│ ├── version.txt
│ └── ...
├── demos/
│ ├── manifests/ ← Demo Manifest Git 仓库(ls-demos 与 new -r 共享)
│ ├── .git/
│ ├── demo_a/
│ │ └── v1.0.0/
│ │ └── default.xml
│ └── demo_b/
│ └── v2.0.0/
│ └── default.xml
└── libraries/
├── manifests/ ← 库 Manifest Git 仓库
│ ├── .git/
│ ├── component_a/
│ │ ├── v1.0.0/
│ │ │ └── default.xml
│ │ └── v2.0.0/
│ │ └── default.xml
│ └── component_b/
│ └── v1.2.0/
│ └── default.xml
├── component_a/
│ ├── v1.0.0/
│ │ ├── version.txt ← 内容为 "1.0.0"
│ │ └── ... ← 库源码
│ └── v2.0.0/
│ ├── version.txt
│ └── ...
└── component_b/
└── v1.2.0/
├── version.txt
└── ...
版本增量管理: 不同版本独立存储,互不覆盖。切换版本只需修改 env_config.json 中的版本号后重新执行 env-setup。
8. 典型工作流
场景一:新建项目并首次编译
# 第 1 步:创建项目
unirtos-cli new unirtos-app
cd unirtos-app
# 第 2 步:配置 env_config.json
# 必填:build.module、sdk.version
# 按需填写:build.version、build.jobs、libraries.list
# 第 3 步:拉取 SDK 和库(首次需联网)
unirtos-cli env-setup
# 第 4 步:编译
unirtos-cli build
# 编译产物在:./qos_build/release/<version>/
场景二:切换 SDK 版本
# 1. 修改 env_config.json 中的 sdk.version 为新版本,例如 "2.2.0"
# 2. 拉取新版本
unirtos-cli env-setup
# 3. 重新编译
unirtos-cli build
场景三:查询可用版本后添加依赖库
# 查看远端有哪些库可用
unirtos-cli ls-libs -r
# 查看某库的可用版本,在 JSON 中确认
unirtos-cli ls-libs -r -j
# 在 env_config.json 的 libraries.list 中添加:
# { "name": "component_b", "version": "1.2.0" }
# 重新执行 env-setup 拉取新库
unirtos-cli env-setup
# 重新编译(库会自动被 SDK CMake 集成进固件)
unirtos-cli build
场景四:基于远程 demo 创建项目
# 基于远程 demo(自动选择最新版本)创建项目
unirtos-cli new -r demo_a
# 基于远程 demo 指定版本创建项目
unirtos-cli new -r demo_a -v 1.0.0
# 进入新建目录(目录名自动带版本后缀)
cd demo_a-1.0.0
# 拉取 SDK 与依赖
unirtos-cli env-setup
# 编译
unirtos-cli build
说明:
new -r会使用本地缓存的<unirtos_root>/demos/manifests(必要时按策略更新)。- 目标目录固定为
<project-name>-<version>,即使未显式传-v也会自动拼接版本号。 - 如需强制刷新 demo manifests,可加
-f:unirtos-cli new -r demo_a -f。
场景五:清理后重新编译
unirtos-cli clean
unirtos-cli build
9. 常见问题
Q1:env-setup 时提示 "git not found"
原因: 系统未安装 Git 或 Git 不在 PATH 中。
解决: 安装 Git 并确保终端中 git --version 能正常输出,然后重新执行。
Q2:build 时提示 'unirtos' command not found
原因: UniRTOS 交叉编译工具链未安装,或未添加到 PATH。
解决: 安装官方工具链包,按其说明将工具链目录添加到系统 PATH,重新打开终端后再执行编译。
Q3:build 时提示 SDK v2.1.0 not found
原因: 尚未执行 env-setup,或 sdk.version 与已拉取的版本不一致。
解决:
unirtos-cli env-setup # 拉取配置文件中指定的 SDK 版本
unirtos-cli build
Q4:env-setup 后 ls-sdk 显示 SDK 版本未变化
原因: ls-sdk 默认显示本地版本(读取 version.txt),需使用 -r 查看远端可用版本。
unirtos-cli ls-sdk # 本地已安装版本
unirtos-cli ls-sdk -r # 远端可用版本
Q5:远端版本列表不是最新的
原因: Manifest 仓库缓存未过期(默认 1 小时刷新一次)。
解决: 使用 -f 强制刷新:
unirtos-cli ls-sdk -r -f
unirtos-cli ls-libs -r -f
unirtos-cli ls-demos -f
Q6:多个项目共用同一个 SDK,如何配置
unirtos_root 字段控制所有版本的统一存储位置,默认 ~/.unirtos。多个项目可以在各自的 env_config.json 中留空(共享默认路径),不同版本会独立共存,互不干扰。如需隔离存储,填入不同路径即可:
{
"unirtos_root": "/opt/unirtos-workspace",
...
}
Q7:如何在离线环境中使用
在联网机器上执行一次 env-setup 完成所有拉取后,将整个 ~/.unirtos/ 目录复制到离线机器的同路径下,然后 env-setup 会因版本匹配直接跳过拉取步骤,build 可正常使用。
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file unirtos_cli-1.0.14.tar.gz.
File metadata
- Download URL: unirtos_cli-1.0.14.tar.gz
- Upload date:
- Size: 42.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.12.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
d91264605430df0ec21d20fc8c47bd4af8e88b4ef7b712c3d8d661e3fd11ab0f
|
|
| MD5 |
d7f038d6d98480cbcef4e401c1d864f3
|
|
| BLAKE2b-256 |
2f09110b2b98a6db8fe24a9f091e5e72c27713e412c626e644446ddd56cce70e
|
File details
Details for the file unirtos_cli-1.0.14-py3-none-any.whl.
File metadata
- Download URL: unirtos_cli-1.0.14-py3-none-any.whl
- Upload date:
- Size: 36.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.12.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c8fd6a31cbca636582f41e27b68e14e40ad2af7c82cca556da4dafb76a83e2ee
|
|
| MD5 |
475daf7df810c3874d40661776c085c6
|
|
| BLAKE2b-256 |
8d6585872827f2af6ca1254ac0621fd2cd009f39deaf4655d3d532c0a4922898
|