open-vela · tanghao-xiaomi · Feb 6, 2026 · Feb 6, 2026
@@ -86,6 +86,14 @@ Below are the currently released stable versions and their change logs:
 
 - **trunk-5.2**: Please refer to the [v5.2 Release Notes](./en/release_notes/v5.2.md) for detailed changes.
 
+### Hardware Adaptation Guide
+
+To maximize efficiency and ensure code stability, we offer the following recommendations for developers performing hardware porting:
+
+- **Recommended Baseline**: We strongly recommend **basing your development on the latest openvela release version** (i.e., Release Tags on the `trunk` branch).
+- **Risk Warning**: The current **`dev` branch** is undergoing rapid iteration with frequent code updates. It may be subject to underlying interface changes or temporary instability. Therefore, it is **NOT recommended** as a baseline for hardware adaptation.
+- **Get Support**: If you have adaptation requirements or encounter technical difficulties, please feel free to **submit an Issue** or contact us via the **WeChat Community**. The openvela team is ready to provide the necessary development support.
+
 ### Version Maintenance Strategy
 
 openvela follows a strict version maintenance lifecycle:

@@ -87,6 +87,14 @@ Vela 的命名源自拉丁语中船帆的含义，也是南方星空中船帆星
 
 - **trunk-5.2**：请查阅 [v5.2 版本发布说明](./zh-cn/release_notes/v5.2.md) 了解详细变更。
 
+### 硬件适配特别说明 (Hardware Adaptation Guide)
+
+为提升适配效率并确保代码稳定性，针对进行硬件移植（Porting）的开发者，我们提供以下建议：
+
+- **推荐基准**：建议**优先基于 openvela 最新发布版本**（即 `trunk` 上的 Release Tag）进行硬件适配开发。
+- **风险提示**：当前 **`dev` 分支** 处于快速迭代期，代码更新较为频繁，可能存在底层接口变动或临时性问题，**不推荐**作为硬件适配的基准代码。
+- **获取支持**：如有适配需求或在过程中遇到技术疑问，欢迎**提交 Issue** 或者通过**微信社区**与我们取得联系，openvela 团队将提供必要的开发支持。
+
 ### 版本维护策略
 
 openvela 遵循严格的版本维护生命周期：

@@ -158,106 +158,72 @@ After installation, you can run `repo --version` to verify it.
         repo init -u https://gitcode.com/open-vela/manifests.git -b dev -m openvela.xml --repo-url=https://mirrors.tuna.tsinghua.edu.cn/git/git-repo/ --git-lfs
         ```
 
-3. Run the sync command. `repo` will download all relevant source code repositories according to the manifest file (`openvela.xml`).
+3. Execute the sync command. `repo` will download all related source code repositories according to the manifest file (`openvela.xml`).
 
-    ```Bash
+    ```bash
     repo sync -c -j8
     ```
 
-## Step 3: Compile the Source Code
-
-After downloading the source code, perform the following build steps in the openvela root directory.
-
-### 1. Set Up Environment Variables
-
-Run the following commands to add the prebuilt toolchain paths to the environment variables for the current terminal session.
-
-```Bash
-uname_s=$(uname -s | tr '[A-Z]' '[a-z]')
-uname_m=$(uname -m | sed 's/arm64/aarch64/g')
-export PATH=$PWD/prebuilts/build-tools/${uname_s}-${uname_m}/bin:$PATH
-export PATH=$PWD/prebuilts/cmake/${uname_s}-${uname_m}/bin:$PATH
-export PATH=$PWD/prebuilts/python/${uname_s}-${uname_m}/bin:$PATH
-export PATH=$PWD/prebuilts/gcc/${uname_s}-${uname_m}/aarch64-none-elf/bin:$PATH
-export PATH=$PWD/prebuilts/gcc/${uname_s}-${uname_m}/arm-none-eabi/bin:$PATH
-export PYTHONPATH=$PWD/prebuilts/tools/python/dist-packages/cxxfilt
-export PYTHONPATH=$PWD/prebuilts/tools/python/dist-packages/kconfiglib:$PYTHONPATH
-export PYTHONPATH=$PWD/prebuilts/tools/python/dist-packages/pyelftools:$PYTHONPATH
-```
-
-> **Note**: This environment variable configuration is only valid for the current terminal window. If you open a new terminal, you must run this script again.
-
-### 2. Configure the CMake Project (Out-of-Tree)
+    ![alt text](./figures/004.png)
 
-openvela uses an **Out-of-tree build** approach, which separates the build artifacts from the source code to keep the source directory clean.
+    > **Tip**
+    >
+    > - The initial sync can be time-consuming, depending on your network connection and disk performance.
+    > - If the sync is interrupted due to network issues, you can run `repo sync` again to resume.
 
-Run the following `cmake` command to configure the project. This command will:
+## Step 3: Compile Source Code
 
-- Generate the build system files in the `cmake_out/goldfish-arm64-v8a-ap` directory.
-- Use Ninja as the build tool to improve compilation speed.
-- Specify the configuration file for the target board.
+After downloading the source code, execute the following compilation steps in the openvela root directory.
 
-```Bash
-cmake \
-  -B cmake_out/goldfish-arm64-v8a-ap \
-  -S $PWD/nuttx \
-  -GNinja \
-  -DBOARD_CONFIG=../vendor/openvela/boards/vela/configs/goldfish-arm64-v8a-ap \
-  -DEXTRA_FLAGS="-Wno-cpp -Wno-deprecated-declarations"
-```
+### 1. (Optional) Custom Kernel Configuration
 
-![alt text](./figures/005.png)
-
-### 3. (Optional) Customize Kernel Configuration
-
-You can use the `menuconfig` command to open a graphical interface for adjusting the NuttX kernel and component configurations.
+You can use the `menuconfig` command to open a graphical interface to adjust the NuttX kernel and component configurations.
 
 ```Bash
-cmake --build cmake_out/goldfish-arm64-v8a-ap -t menuconfig
+./build.sh vendor/openvela/boards/vela/configs/goldfish-arm64-v8a-ap/ --cmake menuconfig
 ```
 
-> **Tips**
+> **Operation Tricks**
 >
-> - Press `/` to search for a configuration item.
-> - Press the `Spacebar` to toggle the selection state (enable/disable/modularize).
-> - After configuring, select **Save** to save and exit.
+> - Press `/` to search for configuration items.
+> - Press `Space` to toggle selection status (Enable/Disable/Modularize).
+> - After configuration, select **Save** to save and exit.
 
-![alt text](./figures/006.png)
+<img src="./figures/006.png" alt="" width="75%">
 
-### 4. Run the Build
+### 2. Execute Compilation
 
-Run the following command to build the entire project.
+Execute the following command to build the entire project.
 
 ```Bash
-cmake --build cmake_out/goldfish-arm64-v8a-ap
+./build.sh vendor/openvela/boards/vela/configs/goldfish-arm64-v8a-ap/ --cmake -j$(nproc)
 ```
 
-After a successful build, you will find `nuttx` and other build artifacts in the `cmake_out/goldfish-arm64-v8a-ap` directory.
+Upon successful compilation, you will find build artifacts such as `nuttx` in the `cmake_out/vela_goldfish-arm64-v8a-ap` directory.
 
-![alt text](./figures/007.png)
+<img src="./figures/007.png" alt="" width="75%">
 
-## Step 4: Run the Emulator
+## Step 4: Run Emulator
 
-In the openvela root directory, run the following script to start the `Vela Emulator` and load your build artifacts.
+In the openvela root directory, execute the following script to start the `Vela Emulator` and load your build artifacts.
 
 ```Bash
-./emulator.sh cmake_out/goldfish-arm64-v8a-ap
+./emulator.sh cmake_out/vela_goldfish-arm64-v8a-ap/
 ```
 
-After the emulator starts, you will see the `goldfish-armv8a-ap>` prompt, indicating that openvela is running successfully.
-
-![alt text](./figures/008.png)
+After the emulator starts, you will see the `goldfish-armv8a-ap>` prompt, indicating that openvela has run successfully.
 
-![alt text](./figures/009.png)
+<img src="./figures/008.png" alt="" width="75%">
 
 ## Next Steps
 
 - Frequently Asked Questions
 
     - [Quick Start FAQ](../faq/QuickStart_FAQ.md)
+    - [Developer FAQ](../faq/QuickStart_FAQ.md)
 
 - Further Reading
 
-    - [Debugging with the Emulator](./emulator/Debugging_Vela_with_Vela_Emulator.md)
-    - [ADB Commands](./emulator/Android_Debug_Bridge_commands.md)
-    - [Sending Emulator Console Commands](./emulator/Send_emulator_console_commands.md)
+    - [Debugging Vela with the Vela Emulator](./emulator/Debugging_Vela_with_Vela_Emulator.md)
+    - [Android Debug Bridge commands](./emulator/Android_Debug_Bridge_commands.md)
+    - [Send emulator console commands](./emulator/Send_emulator_console_commands.md)
@@ -220,6 +220,7 @@ sudo mv repo /usr/local/bin
 - 常见问题
 
     - [快速入门常见问题](../faq/QuickStart_FAQ.md)
+    - [开发者常见问题解答](../faq/devoloper_tech_faq.md)
 
 - 进一步阅读