# unirtos-cli使用教程

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

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

**适用平台：** Windows。

# 前提条件

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

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

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

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

# 安装

执行以下命令进行安装：

```bash
pip install unirtos-cli
```

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

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

```bash
pip install --upgrade unirtos-cli
```

# 快速开始

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

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

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

# 4. 编译
unirtos-cli build
```

```{note}
**env-setup** 执行完成后，会在App根目录自动生成 *<app-name>.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仓库镜像源

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

```powershell
unirtos-cli git-mirror [<mirror>]
```

- **`<mirror>`** 可选值：github和gitee。

- 若省略 **`<mirror>`**，则查询当前配置。

- 若从未配置过 **`<mirror>`**，则默认值为github。

## 完整示例

```json
{
  "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 — 查询或设置全局镜像源

```powershell
unirtos-cli git-mirror [<mirror>]
```

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

**示例：**

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

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

# 切回 github
unirtos-cli git-mirror github
```

## new — 创建新项目

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

1. 模板模式（默认）：基于app-tmpl创建项目。

2. 示例模式（*-r/--from-demo*）：基于远程同名示例仓库创建项目。

```bash
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* | .（当前目录） | 项目基目录。最终目录为 *<project-dir>/<project-name>* |
| *-f, --force* | 关闭 | 强制更新 *`<unirtos_root>`/demos/manifests* 后再选示例。仅可与 *-r* 同时使用 |

```{note}
模板模式下（不带 *-r*），系统会自动将新项目 *env_config.json* 中的 *sdk.version* 设置为最新可用SDK版本。
```

**示例：**

```powershell
# 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和所有依赖库到本地存储目录。

```powershell
unirtos-cli env-setup [-d <project-dir>]
```

| **参数** | **默认值** | **说明** |
| --- | --- | --- |
| *-d, --project-dir* | .（当前目录） | 包含 *env_config.json* 的项目目录 |

**示例：**

```powershell
cd unirtos-app
unirtos-cli env-setup
```

## build — 编译项目

调用UniRTOS工具链的 **unirtos make** 命令，以 **SDK驱动** 模式编译当前外部应用。

```powershell
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* > 应用根目录名称 | 固件版本字符串 |

编译生成的固件及相关产物将保存在以下路径中：

```plaintext
<project-dir>/qos_build/release/<version>/
```

**示例：**

```powershell
# 使用 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/* 目录内容）。

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

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

**示例：**

```powershell
unirtos-cli clean
```

## menuconfig — 打开配置菜单

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

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

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

**示例：**

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

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

## version — 查看CLI版本

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

```powershell
unirtos-cli version
```

**示例输出：**

```plaintext
unirtos-cli v1.0.15
```

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

列出本地已安装或远程可用的SDK版本。

```powershell
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*。默认为当前目录 |

**示例：**

```powershell
# 查看本地已安装的 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 — 查看库版本列表

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

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

**ls-libs** 的参数与 **ls-sdk** 的参数完全一致且参数含义相同。

*-d/--project-dir* 同样从该目录向上查找 *env_config.json*；若找到配置文件，则使用其中的 *unirtos_root*，否则回退至 *~/.unirtos*。

**示例：**

```powershell
# 查看本地已安装的库
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 — 查看示例版本列表

列出远程示例及其版本。

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

**示例：**

```powershell
# 查看 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* 已满足外部应用编译要求，通常只需关注以下两点：

1. 将源码目录添加到 *target_sources(...)* 中。

2. 将头文件目录添加到 *target_include_directories(...)* 中。

最常见的自定义方式是扩展源码目录。例如，新增 *components/* 目录后，可按如下方式配置：

```cmake
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* 中按需启用。

```cmake
add_subdirectory_if_exist(app_components)
```

## 推荐落地步骤

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

## 常见失败原因

1. *CMakeLists.txt* 未将新增.c文件添加到 *target_sources()* 中，导致链接缺符号。

2. 头文件目录未添加到 *target_include_directories()* 中，导致编译时找不到头文件。

3. 依赖的底层组件未通过 **menuconfig** 进行正确配置，导致相关API或组件不可用。

# 本地存储目录结构

所有SDK与库源码统一存储在 *unirtos_root*（默认 *~/.unirtos/*）下，其结构如下：

```plaintext
~/.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** 即可。

# 典型工作流

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

```powershell
# 第 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版本

```powershell
# 1. 修改 env_config.json 中的 sdk.version 为新版本，例如 "2.2.0"
# 2. 拉取新版本
unirtos-cli env-setup
# 3. 重新编译
unirtos-cli build
```

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

```powershell
# 查看远端有哪些库可用
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
```

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

```powershell
# 基于远程 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
```

```{note}
1. *new -r* 会使用本地缓存的 *`<unirtos_root>`/demos/manifests*（必要时按策略更新）。
2. 目标目录固定为 *<project-name>-`<version>`* 格式。即使未显式传 *-v*，系统也会自动拼接版本号。
3. 如需强制刷新Demo manifests，可添加参数 *-f* 或完整命令 **unirtos-cli new -r demo_a -f**。
```

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

```powershell
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* 与已拉取的版本不一致。

**方案：**

```powershell
unirtos-cli env-setup   # 拉取配置文件中指定的 SDK 版本
unirtos-cli build
```

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

**原因：** **ls-sdk** 默认显示 **本地** 已安装版本（读取 *version.txt*），需使用 *-r* 查看远端可用版本。

```powershell
unirtos-cli ls-sdk        # 本地已安装版本
unirtos-cli ls-sdk -r     # 远端可用版本
```

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

**原因：** Manifest仓库缓存未过期（默认1小时刷新一次）。

**方案：** 使用 *-f* 强制刷新，例如：

```powershell
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* 中留空（共享默认路径），不同版本会独立共存，互不干扰。如需隔离存储，填入不同路径即可：

```json
{
  "unirtos_root": "/opt/unirtos-workspace",
  ...
}
```

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

在联网机器上执行一次 **env-setup** 完成所有拉取后，将整个 *~/.unirtos/* 目录复制到离线机器的同路径下。之后执行 **env-setup** 时，因版本匹配会直接跳过拉取步骤，build可正常使用。