openvela快速入门：从零搭建开发环境到模拟器运行全攻略

标签：openvela | 嵌入式

本文是《从零开始学openvela》系列第一篇，完整讲解 openvela 开发环境搭建、源码下载编译、模拟器运行与调试，以及常见问题排查。

摘要

openvela 是小米面向 AIoT 场景开源的"Tiny Linux"级操作系统，基于 Apache NuttX 实时内核，可在 32KB 到 512MB RAM 的芯片上提供约 88% POSIX 兼容环境。本文围绕"快速入门"主线，系统讲解从环境搭建、源码获取、交叉编译到模拟器运行的完整流程。

1.1 环境准备

1.1.1 系统与硬件需求

操作系统：

  • 发行版：Ubuntu 22.04 LTS 64-bit（官方 CI 与文档基于此版本验证）
  • 内核：≥ 5.15（对 USB 设备、FUSE、BPF 等调试功能更友好）
  • 禁止环境：WSL1/WSL2、Docker、虚拟机快照盘（均会因 inode 或权限问题导致编译失败）

硬件需求：

  • CPU：64 位 x86 架构（支持虚拟化指令集 VT-x/AMD-V 更佳）
  • 内存：≥ 16GB RAM（低于 16GB 会在并行编译或链接阶段出现 OOM 被杀进程）
  • 硬盘：剩余空间 ≥ 80GB（源码 + 编译产物 + ccache 临时文件合计约 60GB+）
  • 外设：有线网络（git 仓库与工具链下载量 > 5GB）

1.1.2 具体操作步骤

在 Ubuntu 22.04 上准备 openvela 开发环境分五步完成：

1. 安装必备的软件包
sudo apt install \
bison libgmp-dev libmpc-dev libmpfr-dev libisl-dev binutils-dev libelf-dev \
libexpat1-dev gcc-multilib g++-multilib picocom u-boot-tools util-linux \
dfu-util libx11-dev libxext-dev net-tools pkgconf unionfs-fuse zlib1g-dev \
libusb-1.0-0-dev libv4l-dev libuv-dev npm nodejs nasm yasm libdivsufsort-dev \
libc++-dev libc++abi-dev libprotobuf-dev protobuf-compiler protobuf-c-compiler mtools

各包说明：

  • bison：语法分析器生成器，构建系统需要
  • libgmp-dev 等：数学运算库，编译器依赖
  • gcc-multilib / g++-multilib：支持 32 位和 64 位交叉编译
  • dfu-util：用于烧录固件
  • libx11-dev、libxext-dev：图形界面支持（模拟器需要）
  • npm、nodejs：前端工具链
  • protobuf 相关：用于序列化通信协议
  • mtools：用于操作 FAT 文件系统镜像
2. 安装 Repo 工具

Repo 是 Google 提供的多 Git 仓库管理工具，openvela 用它管理源码：

curl https://storage.googleapis.com/git-repo-downloads/repo > repo
chmod +x repo
sudo mv repo /usr/local/bin/

如果无法访问 Google 源，可使用清华镜像：将 URL 替换为 https://mirrors.tuna.tsinghua.edu.cn/git/git-repo

3. 安装 KConfig 前端
sudo apt install kconfig-frontends

如果系统未提供该包，可从 NuttX 的 tools 仓库中源码构建。

4. 安装 Python 环境
sudo apt install python3 python3-pip python-is-python3

python-is-python3：将 python 命令指向 python3，避免兼容性问题。

5. 安装 Python 依赖包
sudo pip3 install kconfiglib pyelftools cxxfilt
  • kconfiglib：解析 KConfig 文件
  • pyelftools：分析 ELF 格式二进制文件
  • cxxfilt：C++ 符号解析（调试/分析时用）

1.2 下载 openvela 源码

openvela 源码托管在 GitHub、Gitee 和 GitCode 三个平台，采用多仓库 + repo 工具管理。主仓库（manifest）只保存仓库列表，各子模块源码分放在独立仓库中。

1.2.1 前置条件

  1. 网络连通性：需稳定访问 GitHub/Gitee/GitCode 之一，否则 repo sync 会报 fetch-timeout
  2. 已安装 repo：openvela 采用多仓库（>40 个子仓）管理
  3. Git LFS：仓库预置了编译链、AI 模型、字体资源等单文件 >100MB 的大文件，未安装 LFS 会导致"工具链找不到"或"资源 CRC 不匹配"等编译错误：
sudo apt update
sudo apt install git-lfs

1.2.2 操作步骤

1. 工作目录建立
mkdir vela-opensource
cd vela-opensource

路径尽量全小写、无空格，避免 Windows 双系统下大小写冲突。

2. 选择代码源与初始化仓库

官方同时维护三套镜像，推荐使用 HTTPS 协议，原因如下：

维度 HTTPS SSH
配置成本 几乎为零，首次输入 PAT 即可 需生成密钥对，上传公钥到各平台
网络兼容性 默认端口 443，任何能上网的环境就通 端口 22，部分网络环境会屏蔽
令牌管理 PAT 可随时生成、撤销、设过期 密钥长期有效，泄露风险大 
repo init -u https://github.com/open-vela/manifests.git -b main
3. 同步源码
repo sync -c -j8

-j8：同时开 8 个并发进程，可根据电脑配置调整。-c：只拉取当前分支，减小下载量。

1.3 编译 openvela 源码

build.sh 是官方封装的"一键编译"脚本，完成 make distclean / configure / make 全流程。用法模板：

./build.sh <config_path> [extra_make_args]

其中 vendor/<vendor name>/boards/<board name> 是 openvela 的配置树标准路径。编译 goldfish 模拟器目标：

./build.sh vendor/openvela/boards/vela/configs/goldfish-armeabi-v7a-ap -j8

1.4 在模拟器上运行编译产物

Goldfish-qemu 是以 Android 官方模拟器（qemu-system-goldfish）为基底，裁剪 Android 专用启动链，植入 NuttX 内核加载器和 openvela 虚拟硬件集合后形成的 openvela 专属模拟器。

模拟器优势：

  1. 开发测试便捷：无需实体设备即可模拟 openvela 设备，测试应用和驱动
  2. 跨平台适配：支持 Linux x86_64/arm64、macOS x86_64/aarch64、Windows x64 等多种 Host；支持 arm、arm64、x86、x86_64 等多种 Target
  3. Goldfish 专有驱动：已实现多种 goldfish 驱动，覆盖显示、输入、音频、传感器等多类外设

1.4.1 运行模拟器

# 切换到 openvela 仓库根目录
./emulator.sh vela

在模拟器启动并进入 NSH 后，执行 LVGL 演示：

openvela-ap> lvgl demo &

1.4.2 控制模拟器

模拟器启动后有两类常用控制方式：

一、ADB 命令

ADB 基于 Client-Server 架构，包含三个组件：

  • 客户端：运行在 PC 上，发起指令的入口
  • 服务器：PC 后台进程，绑定 TCP 端口 5037，管理与设备的连接
  • adbd 守护进程：运行在设备端，接收并执行命令

常用命令：

# 查询设备
adb devices

# 发送 Shell 命令
adb shell ls /

# 交互式 Shell
adb shell
# 退出：exit 或 Ctrl+D

# 端口转发（将本地 6100 转发到设备 7100）
adb forward tcp:6100 tcp:7100

# 文件传输
adb push /local/file /data/
adb pull /data/file /local/

# 重启 ADB 服务器（解决卡死问题）
adb kill-server
二、模拟器控制台命令

控制台命令直接对接模拟器核心服务，支持硬件模拟、环境调控等底层操作。

# 通过 telnet 连接控制台（端口默认 5554）
telnet localhost 5554

# 身份认证（token 在 ~/.emulator_console_auth_token 文件中）
auth <auth_token>

# 常用控制台命令
help              # 命令概览
help-verbose      # 完整命令说明
power display     # 查看电池状态
power capacity 80 # 设置电量 80%
geo fix 116.4 39.9 100  # 设置 GPS 位置（经度 纬度 海拔）

控制台命令分六类：常规命令、端口重定向、地理位置、虚假硬件事件、电源状态控制和传感器管理。

1.4.3 使用模拟器调试

一、GDB 调试
# 安装 GDB 多架构调试器
sudo apt install gdb-multiarch

# 启动模拟器调试模式（-S 暂停等 GDB，-s 监听 1234 端口）
./emulator.sh vela -qemu -S -s

# 新终端，连接 GDB
gdb-multiarch nuttx/nuttx
(gdb) target remote localhost:1234

# 调试操作
(gdb) b nx_start     # 在 nx_start 函数设置断点
(gdb) c              # 继续执行
(gdb) l              # 查看源代码
(gdb) info break     # 查看断点信息
(gdb) disable 1      # 禁用 1 号断点
(gdb) d 1            # 删除 1 号断点
(gdb) q              # 退出
二、VS Code 调试配置

安装 VS Code 并配置 .vscode/launch.json：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug openvela",
            "type": "cppdbg",
            "request": "launch",
            "program": "${workspaceFolder}/nuttx/nuttx",
            "cwd": "${workspaceFolder}",
            "MIMode": "gdb",
            "miDebuggerPath": "/usr/bin/gdb-multiarch",
            "miDebuggerServerAddress": "localhost:1234"
        }
    ]
}

然后在终端启动模拟器 ./emulator.sh vela -qemu -S -s，再在 VS Code 中按 F5 启动调试。

三、CLion 远程调试
  1. 安装 CLion：sudo snap install clion --classic
  2. 配置 SSH 连接到虚拟机（Settings → SSH Configurations）
  3. 通过 Remote Development 加载 openvela 源码工程
  4. 创建 Remote GDB Server 调试配置，target remote args 设为 localhost:1234
  5. 启动模拟器后开始调试

1.5 快速入门常见问题

问题一：无法读取远程仓库（SSH 鉴权失败）

错误现象：Permission denied (publickey)

原因：未配置 SSH 公钥或公钥不匹配

解决步骤：

# 1. 检查是否已有 SSH 密钥
ls -la ~/.ssh

# 2. 如果没有，生成密钥对
ssh-keygen -t rsa -C "your_email@example.com"

# 3. 复制公钥
cat ~/.ssh/id_rsa.pub

# 4. 将公钥添加到 GitHub/Gitee → Settings → SSH Keys

# 5. 验证连接
ssh -T git@github.com

问题二：无法访问 Google 源代码仓库

错误现象：fatal: unable to access 'https://gerrit.googlesource.com/git-repo/'

解决方法——替换 Repo 源为国内镜像：

临时指定：

repo init --repo-url=https://mirrors.tuna.tsinghua.edu.cn/git/git-repo <其他参数>

永久修改：

sudo sed -i 's#https://gerrit.googlesource.com/git-repo#https://mirrors.tuna.tsinghua.edu.cn/git/git-repo#' /usr/bin/repo

备用中科大源：https://mirrors.ustc.edu.cn/aosp/git-repo

问题三：repo sync 中断或超时

# 使用 -c 仅拉当前分支，-j4 降低并发
repo sync -c -j4

# 中断后可反复执行，repo 支持断点续传

问题四：编译时 OOM（内存不足被杀）

# 降低并行编译线程数
./build.sh <config> -j2

# 或仅编译必要目标
make -j2

问题五：Qt 插件初始化失败

确保系统安装了 Qt5 相关库：

sudo apt install qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools

问题六：模拟器无法启动

检查 /dev/kvm 权限：

sudo chmod 666 /dev/kvm
# 或
sudo usermod -a -G kvm $USER
# 重新登录后生效

1.6 添加 HelloWorld 示例

1.6.1 创建示例框架

在 apps/examples/ 下创建 helloworld 目录。

1.6.2 编写应用代码

// apps/examples/helloworld/helloworld.c
#include <nuttx/config.h>
#include <stdio.h>

int main(int argc, char *argv[])
{
    printf("Hello, openvela!\n");
    return 0;
}

1.6.3 配置编译选项

# apps/examples/helloworld/Kconfig
config EXAMPLES_HELLOWORLD
    bool "HelloWorld example"
    default n
    ---help---
        A simple HelloWorld example for openvela.

1.6.4 定义构建规则

# apps/examples/helloworld/Makefile
include $(APPDIR)/Make.defs

PROGNAME = helloworld
PRIORITY = SCHED_PRIORITY_DEFAULT
STACKSIZE = 2048
MODULE = CONFIG_EXAMPLES_HELLOWORLD

MAINSRC = helloworld.c

include $(APPDIR)/Application.mk

1.6.5 图形化配置

# 进入 menuconfig
make menuconfig
# 路径：Application Configuration → Examples → HelloWorld example
# 勾选并保存

1.6.6 编译与运行

make -j8
# 烧录或在模拟器中运行后
nsh> helloworld
Hello, openvela!

1.7 Vendor 代码仓说明

1.7.1 核心功能

Vendor 代码仓用于管理各厂商的：

  • Board 级配置（.config + Make.defs）
  • 芯片适配代码
  • 厂商私有驱动和应用

1.7.2 目录结构解析

vela-opensource/
├── nuttx/          # NuttX 内核
├── apps/           # 应用层代码
├── frameworks/     # 框架层
└── vendor/         # 厂商代码专属空间
    └── openvela/
        ├── boards/ # 开发板配置
        │   └── vela/
        │       └── configs/  # .config + Make.defs
        └── chips/  # 芯片适配

1.7.3 第三方代码提交流程

  1. Fork 目标仓库
  2. 在 vendor/<厂商名>/ 下创建独立目录
  3. 提交 PR 到主仓库
  4. 经过 Code Review 后合入

1.7.4 权限管理与版本控制

  • 各厂商仅能修改自己目录下的文件
  • 使用 Git LFS 管理大文件（工具链、资源文件等）
  • 版本通过 manifest 仓库统一管理

小结

本文从零开始完整覆盖了 openvela 开发环境的搭建全流程：

  1. Ubuntu 22.04 工具链安装
  2. 源码下载与 repo 多仓库管理
  3. 一键编译生成可执行镜像
  4. Goldfish-QEMU 模拟器运行与调试
  5. ADB/控制台双通道控制
  6. 六大常见故障排查
  7. HelloWorld 示例与 Vendor 代码仓结构

下一篇将介绍基于 AloT-IDE 的快应用开发。

# openvela
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

Ozon选品工具选购指南：三类工具各有千秋，新手如何不踩坑？

avatar AtomGit开源社区
cover

收藏！小白程序员必看：从零入门AI Agent，抓住2026年高薪风口！

avatar AtomGit开源社区
cover

收藏！2026年大模型时代程序员必看，别被AI浪潮甩在身后

avatar AtomGit开源社区