Skip to main content

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_urlsdk.manifest_repo_branchlibraries.manifest_repo_urllibraries.manifest_repo_branchdemos.manifest_repo_urldemos.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 仓库分支名。留空或省略时,按优先级自动尝试:mainmaster;填写后优先使用该分支。

libraries 对象

字段 类型 必填 说明
manifest_repo_url string 库 Manifest 仓库地址。省略时使用官方默认地址。
manifest_repo_branch string 库 Manifest 仓库分支名。留空或省略时,按优先级自动尝试:mainmaster;填写后优先使用该分支。
list array 依赖库列表。每项包含 name(库名)和 version(版本号)两个字段。不需要任何外部库时可省略 list 或置为空数组 []

demos 对象

字段 类型 必填 说明
manifest_repo_url string Demo Manifest 仓库地址。省略时使用官方默认地址。
manifest_repo_branch string Demo Manifest 仓库分支名。留空或省略时,按优先级自动尝试:mainmaster;填写后优先使用该分支。
库列表项
字段 类型 必填 说明
name string 库名称,需与 Manifest 仓库中的目录名一致。
version string 库版本号,例如 2.0.0

5. 命令参考

5.1 new — 创建新项目

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

  1. 模板模式(默认):基于 app-tmpl 创建项目。
  2. 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.0v1.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 点:

  1. 将你的源码目录加入 target_sources(...)
  2. 将你的头文件目录加入 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 常见失败原因

  1. CMakeLists.txt 未将新增 .c 文件加入 target_sources,导致链接缺符号。
  2. 头文件目录未加入 target_include_directories,导致编译找不到头文件。
  3. 依赖的底层组件未通过 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

说明:

  1. new -r 会使用本地缓存的 <unirtos_root>/demos/manifests(必要时按策略更新)。
  2. 目标目录固定为 <project-name>-<version>,即使未显式传 -v 也会自动拼接版本号。
  3. 如需强制刷新 demo manifests,可加 -funirtos-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-setupls-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

unirtos_cli-1.0.14.tar.gz (42.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

unirtos_cli-1.0.14-py3-none-any.whl (36.8 kB view details)

Uploaded Python 3

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

Hashes for unirtos_cli-1.0.14.tar.gz
Algorithm Hash digest
SHA256 d91264605430df0ec21d20fc8c47bd4af8e88b4ef7b712c3d8d661e3fd11ab0f
MD5 d7f038d6d98480cbcef4e401c1d864f3
BLAKE2b-256 2f09110b2b98a6db8fe24a9f091e5e72c27713e412c626e644446ddd56cce70e

See more details on using hashes here.

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

Hashes for unirtos_cli-1.0.14-py3-none-any.whl
Algorithm Hash digest
SHA256 c8fd6a31cbca636582f41e27b68e14e40ad2af7c82cca556da4dafb76a83e2ee
MD5 475daf7df810c3874d40661776c085c6
BLAKE2b-256 8d6585872827f2af6ca1254ac0621fd2cd009f39deaf4655d3d532c0a4922898

See more details on using hashes here.

Release history Release notifications | RSS feed

1.0.20

2 files

1.0.19

2 files

1.0.18

2 files

1.0.17

2 files

1.0.16

2 files

1.0.15

2 files

This release

1.0.14 This release

2 files

1.0.13

2 files

1.0.12

2 files

1.0.11

2 files

1.0.10

2 files

1.0.9

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page