14.1.1.1. 設定開發環境¶

在能夠編譯之前，你需要在主機上準備三樣東西：一個編輯器（建議使用 VS Code，因為偵錯工具可整合進去）、一個 Linux 風格的 shell（Windows 上使用 WSL，Linux/macOS 上則為原生環境），以及已解壓縮固定版本 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（在開始按鈕上按右鍵 -> 終端機（系統管理員））。
使用預設的 Ubuntu 發行版安裝 WSL:
```
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 檔案固定）。這個動作具有冪等性——如果正確的版本已安裝，重新執行不會有任何作用；而如果 SDK 遺失或版本不對，一般的建置會中止並顯示 "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	在某些移植平台上用於特定目標檔
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 工具鏈已滿足此要求；出現該錯誤表示有另一個較舊的工具鏈遮蔽了它。