> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs-staging.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用预构建 robotics eSDK 构建 robotics 镜像

使用预构建的平台扩展 SDK (eSDK) 构建 robotics 镜像。

robotics eSDK 是一个由 Qualcomm Linux 镜像生成的安装程序，提供了完整的 Yocto 环境，让你可以同步、修改、编译和安装应用。

## 前提条件

* 一台具有至少 50 GB 可用空间的 Ubuntu 24.04 主机计算机。
* 你已按照 [下载预构建包](./download-the-prebuilt-packages) 中的步骤下载了预构建的 robotics eSDK。

## 使用 eSDK 安装 robotics 镜像

1. 通过运行安装程序脚本安装 eSDK。

   <Note>
     **注意**

     * 有关 eSDK 的位置，请参见 [下载预构建包](./download-the-prebuilt-packages)。
     * 以下步骤以 x86\_64 架构的预构建 eSDK 为例。其他架构的操作类似。
   </Note>

   a. 运行以下命令运行安装程序脚本，示例（**MACHINE:** iq-9075-evk）：

   ```shell theme={null}
   cd <decompressed_workspace>/images/<machine>/sdk
   umask a+rx
   sh ./qcom-robotics-ros2-jazzy-x86_64-qcom-robotics-proprietary-image-armv8-2a-iq-9075-evk-toolchain-ext-2.8.0.sh
   ```

   b. 当你看到以下提示时，按 `Enter` 或输入自定义目录以进行 eSDK 安装。

   ```shell theme={null}
   QCOM Robotics Reference Distro with ROS Extensible SDK installer version 2.8.0
   ==============================================================================
   Enter target directory for SDK (default: ~/qcom-robotics-ros2-jazzy_sdk):
   ```

2. 按照剩余的控制台提示完成安装。

3. 当你看到以下提示时，确认 eSDK 安装成功。
   SDK has been successfully set up and is ready to be used.

   ```text theme={null}
    Extracting SDK.......done
    Setting it up...
    Extracting buildtools...
    Preparing build system...
   ```

   <Note>
     **注意**

     如果安装程序因缺失 Perl 模块错误而失败，请参见 [eSDK 安装因缺失 Perl 模块依赖而失败](./troubleshoot#esdk-installation-fails-due-to-missing-perl-module-dependencies)。
   </Note>

## 使用 eSDK 构建 robotics 镜像

每个 shell 会话中 source 一次环境设置脚本，然后构建你需要的镜像。`<eSDK_install_path>` 默认路径是 `~/qcom-robotics-ros2-jazzy_sdk`。

1. 设置 eSDK 并构建 robotics 镜像。
   ```shell theme={null}
   . environment-setup-armv8-2a-qcom-linux  
   ```

2. 要构建镜像，请针对所需的 recipe 运行 `devtool build-image` 命令：

   ```shell theme={null}
   # Overlay Config #1, fully upstream stack
   devtool build-image qcom-robotics-image

   # Overlay Config #2, full Qualcomm stack
   devtool build-image qcom-robotics-proprietary-image
   ```

3. 从你的机器对应的部署目录收集镜像：

<CodeGroup>
  ```text IQ-9075-EVK theme={null}
  <eSDK_install_path>/tmp/deploy/images/iq-9075-evk/qcom-robotics-proprietary-image-iq-9075-evk.rootfs.qcomflash
  ```

  ```text IQ-8275-EVK theme={null}
  <eSDK_install_path>/tmp/deploy/images/iq-8275-evk/qcom-robotics-proprietary-image-iq-8275-evk.rootfs.qcomflash
  ```
</CodeGroup>

<Note>
  **注意**

  为每台机器使用独立的工作区。在同一个工作区内切换 `MACHINE` 会导致构建失败。有关详情，请参见 [在同一工作区中切换 MACHINE 后 eSDK 构建失败](./troubleshoot#esdk-build-fails-after-switching-machine-in-the-same-workspace)。
</Note>

## 将 robotics 镜像刷写到设备

要将 robotics 镜像刷写到设备，请按照 [刷写 robotics 镜像](./flash-the-robotics-image) 中的步骤操作，使用在 [使用 eSDK 构建 robotics 镜像](#build-the-robotics-image-with-esdk) 中生成的 `qcom-robotics-image` 或 `qcom-robotics-proprietary-image` 镜像。

## 使用 eSDK 开发

robotics eSDK 支持的所有 recipe 都位于 `meta-qcom-robotics-sdk/recipes` 目录中。根据你的需要，使用 `devtool` 添加新的 recipe 或修改现有的 recipe。

有关工作流程的背景信息，请参见 Yocto 文档：[Using devtool in your SDK workflow](https://docs.yoctoproject.org/singleindex.html#using-devtool-in-your-sdk-workflow)。

* 要修改现有的 recipe：

  ```shell theme={null}
  devtool modify <recipe-name>
  ```

  此命令将 recipe 的源码提取到 eSDK 工作区下的本地 Git 仓库（默认在 `workspace/sources/<recipe-name>`），你可以在其中进行修改和提交。

* 要从本地源代码或 Git 仓库添加新的 recipe：

  ```shell theme={null}
  devtool add <recipe-name> <source-location>
  ```

* 修改或添加源代码后，构建 recipe 以验证你的更改：

  ```shell theme={null}
  devtool build <recipe-name>
  ```

* 重新构建 robotics 镜像以使更改生效：

  ```shell theme={null}
  devtool build-image qcom-robotics-proprietary-image
  ```

<Note>
  **注意**

  要将你的更改作为永久 recipe 持久化回 `meta-qcom-robotics-sdk` 层，请使用 `devtool finish <recipe-name> <layer-path>`。有关详细信息，请参见上面链接的 Yocto 文档。
</Note>

## 后续步骤

* [刷写 robotics 镜像](./flash-the-robotics-image) — 将你构建的镜像写入设备。
* [在 QIR SDK 上启用和评估 Qualcomm Linux overlays](./enable-and-evaluate-qualcomm-linux-overlays-on-QIR-SDK) — 安装 Config #2 构建生成的 overlay 包。
* [排查常见问题](./troubleshoot) — 解决 eSDK 安装和构建错误。