14.1.1.1. 搭建开发环境¶

在编译之前，你需要在主机上准备好三样东西：一个编辑器（推荐 VS Code，因为调试器可以集成到其中）、一个 Linux 风格的 shell（Windows 上使用 WSL，Linux/macOS 上为原生 shell），以及包含已解压的固定版本 SDK 的 OpenMV 仓库。

14.1.1.1.1. VS Code¶

任何编辑器都可以用于固件开发——构建只是一条 make 命令，硬件上的调试器也可以从命令行运行。Visual Studio Code 只是最简便的途径：调试固件中的设置会集成到它的 Cortex-Debug 扩展中，因此只要安装了 VS Code，这些页面的其余内容便可开箱即用，无论是构建还是调试。

14.1.1.1.1.1. 安装 VS Code¶

Windows——从 code.visualstudio.com 下载安装程序并运行。请将 VS Code 安装在 Windows 上，而不是 WSL 内部；它通过 WSL 扩展与 WSL 集成，在 Windows 上运行其界面，而编译器、文件和调试器则位于 Linux 中。
macOS——从 code.visualstudio.com 下载 .zip 文件，解压后将 Visual Studio Code.app 拖入 /Applications。或者使用 brew install --cask visual-studio-code。
Linux——从 code.visualstudio.com 安装 .deb / .rpm（例如 sudo apt install ./code_*.deb），或使用发行版的 Snap/Flatpak。

需要安装的扩展（从扩展面板中安装，Ctrl+Shift+X）：

C/C++（ms-vscode.cpptools）——C 源代码导航和 IntelliSense。
Cortex-Debug（marus25.cortex-debug）——通过 GDB 和 J-Link / OpenOCD 服务器进行片上调试。调试固件必需。
WSL（ms-vscode-remote.remote-wsl）——仅限 Windows。让 VS Code 打开位于你的 WSL 发行版内部的文件夹，使编辑器、终端、IntelliSense 和 Cortex-Debug 全部在 Linux 中运行。连接后请将 C/C++ 和 Cortex-Debug 扩展安装到 WSL 主机中一次（VS Code 会就此提示你）。

14.1.1.1.2. 主机 shell¶

你需要一个带有 git 和若干基本工具的 Linux（x86-64）或 macOS（arm64）环境。请选择适合你操作系统的章节。

14.1.1.1.2.1. Windows：安装 WSL¶

WSL 在 Windows 上运行一个真正的 Ubuntu 用户空间。安装完成后，本指南中后续的每一条说明都与原生 Linux 完全相同。

以管理员身份打开 PowerShell（右键点击「开始」->*终端（管理员）*）。
安装 WSL 及默认的 Ubuntu 发行版:
```
wsl --install
```
这会启用所需的 Windows 功能、安装 WSL 2 内核并安装 Ubuntu。如有提示请重启。
重启后，Ubuntu 会启动并要求你创建一个 UNIX 用户名和密码。该账户独立于你的 Windows 账户。
更新发行版:
```
sudo apt update && sudo apt upgrade -y
```
确认你使用的是 WSL 2（必需——此工作流不支持 WSL 1）。在 PowerShell 中:
```
wsl --list --verbose
```
VERSION 列必须显示 2。如果显示 1，请进行转换:
```
wsl --set-version Ubuntu 2
```

小技巧

请在 Linux 文件系统中工作（WSL 中的 ~/），而不要在 /mnt/c/ 下工作。在 Windows 挂载的驱动器上构建会显著变慢，并可能导致文件权限和行尾符问题。请将仓库克隆到你的 WSL 主目录中。

稍后要打开项目时：从「开始」菜单启动 Ubuntu 以获得一个 shell，或者在 Windows 上的 VS Code 中按 Ctrl+Shift+P ->*WSL: Connect to WSL*，然后 File -> Open Folder 并选择 Linux 文件系统中已克隆的仓库。

14.1.1.1.2.2. Linux / WSL 前提条件¶

SDK 提供了编译器，因此只需要少数几个主机软件包:

sudo apt-get update
sudo apt-get install git build-essential

14.1.1.1.2.3. macOS 前提条件¶

仅在 Apple 芯片（arm64）的 macOS 上支持原生构建。使用 Homebrew:

brew install bash make coreutils

（Intel Mac 不是受支持的原生构建主机——请使用构建固件中的 Docker 构建或一个 Linux 虚拟机。）

14.1.1.1.3. 获取源代码¶

克隆仓库及其所有子模块（MicroPython、CMSIS、厂商驱动等）:

git clone --recursive https://github.com/openmv/openmv.git
cd openmv

完整的递归克隆体积很大。如需更快的浅克隆:

git clone --depth=1 https://github.com/openmv/openmv.git
cd openmv
git submodule update --init --depth=1 --no-single-branch
git -C lib/micropython/ submodule update --init --depth=1

备注

构建某个特定开发板时，你也可以让 make 仅拉取该开发板所需的子模块:

make TARGET=<board> submodules

上面显示的显式 git submodule update 已经涵盖了所有内容，因此这一步是可选的。

14.1.1.1.4. 安装 OpenMV SDK¶

在仓库根目录下，运行一次性的 SDK 安装:

make sdk

这会从 download.openmv.io 下载 openmv-sdk-<version>-<os>-<arch>.tar.xz，校验其 SHA-256 校验和，并将其解压到 ~/openmv-sdk-<version>/（版本由仓库的 SDK_VERSION 文件固定）。它是幂等的——如果已安装正确的版本，重新运行不会执行任何操作；如果缺失或版本错误，常规构建会以 "OpenMV SDK not found. Run 'make sdk' to install it." 中止。

SDK 捆绑了构建和调试器所需的一切，全部由 Makefile 自动添加到 PATH 中：

组件	用途
ARM GNU 工具链（`arm-none-eabi-gcc` 14.3）	编译器、链接器，以及用于调试的 `arm-none-eabi-gdb`
LLVM/clang	在某些 port 上用于特定的目标文件
CMake、GNU Make	厂商库的构建编排
Python（可重定位）	构建脚本、`mpy-cross` 辅助工具、签名以及模型工具
STM32CubeProgrammer（`STM32_Programmer_CLI`）	SWD 刷写以及 STM32N6 恢复流程
ST Edge AI	用于 STM32N6 NPU 的神经网络编译器
`dfu-util`	USB DFU 刷写
`gdbrunner`	`make debug` 目标的 GDB 服务器启动器（它所驱动的 Segger J-Link 软件是单独安装的）

警告

OpenMV N6 和 OpenMV AE3 使用 Cortex-M55 内核，需要 GCC 14.3 或更新版本。构建会针对这些目标强制要求此条件，如果在 PATH 中 SDK 自带工具链之前找到了较旧的 arm-none-eabi-gcc，则会以 "Upgrade to GCC 14.3+ for proper CM55 support" 错误中止。捆绑的 SDK 工具链已满足此要求；该错误意味着有另一个较旧的工具链遮蔽了它。