unirtos-cli使用教程¶

版本： unirtos-cli v1.0.15及更高版本。

适用平台： Windows。

前提条件¶

在使用unirtos-cli之前，请确保以下工具已安装并配置到系统PATH：

工具	说明	版本
Python	运行CLI工具本身	3.9及更高版本
Git	拉取SDK与库源码	2.20及更高版本
unirtos-toolchain	提供unirtos命令用于编译	1.0.5及更高版本

在PowerShell中执行以下验证命令：

python --version    # 或python3 --version
git --version
unirtos --version

安装¶

执行以下命令进行安装：

pip install unirtos-cli

安装完成后，unirtos-cli 命令即可在终端全局使用。

执行以下命令升级到最新版本：

pip install --upgrade unirtos-cli

快速开始¶

# 1. 创建并进入项目目录
unirtos-cli new unirtos-app
cd unirtos-app

# 2. 编辑env_config.json（见下文配置文件详解）

# 3. 拉取SDK与依赖库
unirtos-cli env-setup

# 4. 编译
unirtos-cli build

备注

env-setup 执行完成后，会在App根目录自动生成 .code-workspace 文件，可一键在VS Code中打开App、SDK与依赖库代码。

编译产物默认输出到项目目录下的 qos_build/release/<version>/。

配置文件详解 (env_config.json)¶

env_config.json 是项目根目录下的核心配置文件，由 new 命令自动生成模板，用户需在其中填写SDK版本、模块名称等信息。针对基于模板创建项目的场景，sdk.version 会自动写入最新可用的SDK版本。

使用建议（推荐）¶

对于绝大多数用户，日常只需要关注并维护以下字段：

build.module：编译模块型号
build.version：目标版本号
build.jobs：并发编译线程数
sdk.version：SDK版本
libraries.list[].name / libraries.list[].version：依赖库名称与版本

切换Git仓库镜像源¶

使用全局命令配置镜像源：

unirtos-cli git-mirror [<mirror>]

<mirror> 可选值：github和gitee。
若省略 <mirror>，则查询当前配置。
若从未配置过 <mirror>，则默认值为github。

完整示例¶

{
  "unirtos_root": "",
  "build": {
    "module": "EG800ZCN_LA",
    "version": "EG800ZCNLAR01A01_BETA_OCPU_20260513",
    "jobs": 8
  },
  "sdk": {
    "version": "1.0.1",
  },
  "libraries": {
    "list": [
      {
        "name": "lib-name",
        "version": "2.0.0"
      }
    ]
  }
}

字段说明¶

顶层字段¶

字段	类型	必填	说明
unirtos_root	string	否	UniRTOS全局存储根目录的绝对路径。留空时自动使用默认路径：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）进行源码检出并存储

libraries对象¶

字段	类型	必填	说明
list	array	否	依赖库列表。每项包含 name（库名）和 version（版本号）两个字段。不需要任何外部库时可省略 list 或置为空数组[]

库列表项¶

字段	类型	必填	说明
name	string	是	库名称，需与Manifest仓库中的目录名一致
version	string	是	库版本号，例如2.0.0

命令参考¶

git-mirror — 查询或设置全局镜像源¶

unirtos-cli git-mirror [<mirror>]

参数	默认值	说明
mirror	省略	可选值为github与gitee。省略时查询当前镜像

示例：

# 查询当前镜像
unirtos-cli git-mirror

# 切换到 gitee
unirtos-cli git-mirror gitee

# 切回 github
unirtos-cli git-mirror github

new — 创建新项目¶

创建一个新的项目。支持两种模式：

模板模式（默认）：基于app-tmpl创建项目。
示例模式（-r/--from-demo）：基于远程同名示例仓库创建项目。

unirtos-cli new [-r] <project-name> [-v <version>] [-d <project-dir>] [-f]

参数	默认值	说明
project-name	必填	项目名称（仅名称，不允许路径分隔符）
-r, --from-demo	关闭	从远程示例创建项目
-v, --version	省略	指定远程示例版本（支持1.0.0或v1.0.0）。仅可与 -r 同时使用；省略时自动选择最新版本
-d, --project-dir	.（当前目录）	项目基目录。最终目录为 /
-f, --force	关闭	强制更新 `<unirtos_root>`/demos/manifests 后再选示例。仅可与 -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

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

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

环境变量注入

以下环境变量由系统自动处理，无需手动设置：

环境变量	说明
UNIRTOS_EXTERNAL_APP_DIR	当前应用根目录，供SDK CMake定位外部应用
UNIRTOS_EXTERNAL_APP_NAME	应用目录名
UNIRTOS_ROOT	UniRTOS全局存储根目录
UNIRTOS_APP_TARGET_NAME	最终目标名（等于 version 字段）
UNIRTOS_LIBRARIES_JSON	依赖库列表（JSON格式），供SDK CMake集成外部库

clean — 清理构建产物¶

删除项目目录下的所有编译产物（qos_build/ 目录内容）。

unirtos-cli clean [-d <project-dir>]

参数	默认值	说明
-d, --project-dir	.	项目目录

示例：

unirtos-cli clean

menuconfig — 打开配置菜单¶

执行以下命令，打开内核功能开关配置页面。

unirtos-cli menuconfig [-d <project-dir>]

参数	默认值	说明
-d, --project-dir	.（当前目录）	起始目录（向上查找 env_config.json）

示例：

# 在当前项目目录执行
unirtos-cli menuconfig

# 指定项目目录执行
unirtos-cli menuconfig -d /path/to/project

version — 查看CLI版本¶

输出当前安装的unirtos-cli版本号。

unirtos-cli version

示例输出：

unirtos-cli v1.0.15

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 参数可忽略缓存有效期，强制立即更新。

ls-libs — 查看库版本列表¶

列出本地已安装或远程可用的依赖库及其版本。

unirtos-cli ls-libs [-r] [-f] [-j] [-d <project-dir>]

ls-libs 的参数与 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"]
#   }
# }

ls-demos — 查看示例版本列表¶

列出远程示例及其版本。

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"]
#   }
# }

基于模板的应用接入与编译配置¶

本节介绍执行 new 生成项目模板后，如何按需调整应用侧的 CMakeLists.txt 文件，确保应用可被SDK正确识别并完成编译。

CMakeLists.txt最小接入要求¶

模板生成的 CMakeLists.txt 已满足外部应用编译要求，通常只需关注以下两点：

将源码目录添加到 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)

常见失败原因¶

CMakeLists.txt 未将新增.c文件添加到 target_sources() 中，导致链接缺符号。
头文件目录未添加到 target_include_directories() 中，导致编译时找不到头文件。
依赖的底层组件未通过 menuconfig 进行正确配置，导致相关API或组件不可用。

本地存储目录结构¶

所有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 即可。

典型工作流¶

场景一：新建项目并首次编译¶

# 第 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（自动选择最新版本）创建项目
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（必要时按策略更新）。
目标目录固定为 -<version> 格式。即使未显式传 -v，系统也会自动拼接版本号。
如需强制刷新Demo manifests，可添加参数 -f 或完整命令 unirtos-cli new -r demo_a -f。

场景五：清理后重新编译¶

unirtos-cli clean
unirtos-cli build

常见问题¶

Q1：为什么执行env-setup时提示"git not found"？¶

原因： 系统未安装Git或Git不在PATH中。

方案： 安装Git并确保终端中git --version能正常输出，然后重新执行 unirtos-cli env-setup。

Q2：为什么执行build时提示’unirtos’ command not found？¶

原因： UniRTOS交叉编译工具链未安装，或未添加到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可正常使用。

unirtos-cli使用教程¶

前提条件¶

安装¶

快速开始¶

配置文件详解 (env_config.json)¶

使用建议（推荐）¶

切换Git仓库镜像源¶

完整示例¶

字段说明¶

顶层字段¶

build对象¶

sdk对象¶

libraries对象¶

库列表项¶

命令参考¶

git-mirror — 查询或设置全局镜像源¶

new — 创建新项目¶

env-setup — 拉取环境¶

build — 编译项目¶

clean — 清理构建产物¶

menuconfig — 打开配置菜单¶

version — 查看CLI版本¶

ls-sdk — 查看SDK版本列表¶

ls-libs — 查看库版本列表¶

ls-demos — 查看示例版本列表¶

基于模板的应用接入与编译配置¶

CMakeLists.txt最小接入要求¶

推荐落地步骤¶

常见失败原因¶

本地存储目录结构¶

典型工作流¶

场景一：新建项目并首次编译¶

场景二：切换SDK版本¶

场景三：查询可用版本后添加依赖库¶

场景四：基于远程示例创建项目¶

场景五：清理后重新编译¶

常见问题¶

Q1：为什么执行env-setup时提示"git not found"？¶

Q2：为什么执行build时提示’unirtos’ command not found？¶

Q3：为什么执行build时提示SDK v2.1.0 not found？¶

Q4：为什么执行env-setup后ls-sdk显示SDK版本未变化？¶

Q5：为什么远端版本列表不是最新的？¶

Q6：如果多个项目共用同一个SDK，应如何配置？¶

Q7：如何在离线环境中使用¶