📚 课程目录第2章开发环境搭建

2. 开发环境搭建

RK3568 作为一款高性能、低功耗的国产四核 Cortex-A55 应用处理器，其开发复杂度远高于传统的单片机项目。一套完整、稳定且可复现的开发环境，是后续进行内核裁剪、设备树调试以及 Buildroot 根文件系统定制的基础。本章将围绕“从零搭建”这一目标，详细拆解 Ubuntu 宿主机的准备、交叉编译工具链的配置、Rockchip SDK 的获取以及最终的环境验证四个核心环节。我们不仅要解决“怎么装”的问题，更要理解“为什么这样配”，从而在遇到环境类故障时能够快速定位并修复。

上图清晰地展示了从宿主机准备到最终产物生成的完整链路。在实际开发中，环境问题往往不是孤立出现的，例如交叉编译工具链无法执行，可能源于宿主机缺少 32 位兼容库，也可能是因为 SDK 脚本中硬编码了工具链路径。因此，我们采用“分层验证、逐级排查”的策略，确保每一层都稳固后再进入下一层。

2.1 核心原理：为什么需要交叉编译与 SDK 整体结构

交叉编译（Cross Compilation）的本质，是在一种架构（如 x86_64 的 PC）上编译生成另一种架构（如 ARM64 的 RK3568）可执行的机器码。由于 RK3568 的算力、内存和存储资源有限，无法在板卡上直接运行完整的编译工具链（如 GCC、Binutils），因此必须在高性能的宿主机上完成编译，再将产物部署到目标板。交叉编译工具链由 binutils（汇编器、链接器）、gcc（编译器）、glibc（C 库）以及 linux-kernel-headers（内核头文件）组成。Rockchip 官方提供的工具链前缀为 aarch64-none-linux-gnu-，其中 aarch64 表示 64 位 ARM 架构，none 表示无特定厂商（bare-metal 或 Linux 均可），linux-gnu 表示目标系统为 Linux 且使用 GNU C 库。

Rockchip SDK 并非单一仓库，而是一个基于 repo 工具管理的多仓库集合。其核心目录结构如下：

目录/文件	作用说明
`kernel/`	Linux 4.19/5.10 内核源码，包含 arch/arm64/boot/dts/rockchip/ 下的设备树源文件
`u-boot/`	U-Boot 引导加载程序源码，负责初始化 DDR、加载内核
`buildroot/`	Buildroot 构建系统，用于生成根文件系统、交叉工具链（可选）
`device/rockchip/`	板级配置、分区表、恢复模式脚本、`BoardConfig.mk` 文件
`external/`	第三方库、编解码器、GPU 驱动（Mali）、NPU 运行时等
`app/`	Rockchip 预置的应用层程序
`build.sh`	顶层编译脚本，封装了内核、U-Boot、Buildroot 的编译流程

理解 SDK 的结构至关重要。例如，当我们需要修改设备树时，必须进入 kernel/arch/arm64/boot/dts/rockchip/ 目录；当需要调整根文件系统软件包时，则需操作 buildroot/configs/rockchip_rk3568_defconfig。SDK 的版本管理依赖于 .repo/manifest.xml 文件，它锁定了每个子仓库的提交哈希值，确保团队协作时环境一致。

2.2 操作流程：从零搭建环境的五个关键步骤

以下操作均在 Ubuntu 20.04 LTS 64 位系统上验证通过。请确保使用 非 root 用户 执行，并拥有 sudo 权限。

步骤 1：更新系统与安装基础依赖

sudo apt update
sudo apt upgrade -y
# 安装编译内核及 Buildroot 所需的依赖
sudo apt install -y git ssh make gcc libncurses5-dev libncursesw5-dev \
  g++ autoconf automake libtool bison flex texinfo gawk \
  libssl-dev libgmp-dev libmpc-dev libmpfr-dev zlib1g-dev \
  device-tree-compiler python2 python3 python3-pip \
  lz4 zstd unzip rsync file bc u-boot-tools
# 如果使用 repo 工具，需要安装
sudo apt install -y repo

风险提示：Ubuntu 22.04 默认不再提供 python2，而部分旧版 SDK 脚本（如 mkimage）仍依赖 Python 2。若使用 22.04，建议通过 apt install python2 或从源码编译 Python 2.7，并创建软链接 sudo ln -s /usr/bin/python2.7 /usr/bin/python。否则在编译 U-Boot 或内核时可能报 /usr/bin/env: ‘python’: No such file or directory 错误。

步骤 2：配置交叉编译工具链

Rockchip 官方推荐使用 gcc-arm-10.3-x86_64-aarch64-none-linux-gnu 工具链。下载后解压至 /opt/ 目录，并配置环境变量：

# 假设工具链压缩包位于 ~/Downloads/
sudo mkdir -p /opt/arm
sudo tar -xvf ~/Downloads/gcc-arm-10.3-x86_64-aarch64-none-linux-gnu.tar.xz -C /opt/arm/
# 编辑用户环境变量文件
echo 'export PATH=/opt/arm/gcc-arm-10.3-x86_64-aarch64-none-linux-gnu/bin:$PATH' >> ~/.bashrc
echo 'export ARCH=arm64' >> ~/.bashrc
echo 'export CROSS_COMPILE=aarch64-none-linux-gnu-' >> ~/.bashrc
source ~/.bashrc
# 验证版本
aarch64-none-linux-gnu-gcc -v

验证输出应包含 gcc version 10.3 以及 Target: aarch64-none-linux-gnu 字样。注意，ARCH 和 CROSS_COMPILE 环境变量是内核编译系统的核心参数，ARCH 指定目标 CPU 架构，CROSS_COMPILE 指定交叉编译工具链前缀。如果不设置这两个变量，内核 Makefile 会默认使用本机 gcc 进行编译，导致生成 x86 架构的不可用内核。

步骤 3：获取 RK3568 SDK 源码

Rockchip 提供两种获取方式：网盘压缩包 和 repo 同步。对于初学者，推荐使用网盘中的 rk3568_linux_sdk_vX.X.tar.gz 完整包，因为 repo 同步需要访问外网且耗时较长。

# 方式一：解压网盘 SDK 包
mkdir -p ~/rk3568_sdk && cd ~/rk3568_sdk
tar -xvf ~/Downloads/rk3568_linux_sdk_v1.4.0.tar.gz
# 解压后目录内包含 .repo 隐藏目录，需要恢复所有子仓库
.repo/repo/repo sync -l  # 仅从本地对象库恢复工作树
.repo/repo/repo sync -c  # 从远程同步最新代码（可选）

# 方式二：repo 初始化（需先安装 repo 工具）
mkdir -p ~/rk3568_sdk && cd ~/rk3568_sdk
repo init -u https://gitlab.com/firefly-linux/manifests.git -b master
repo sync -j4

经验提醒：解压 SDK 后，务必先执行 .repo/repo/repo sync -l 来恢复 Git 工作树。因为网盘包为了减小体积，将 Git 对象库打包了，但工作区文件是空的。如果不执行此命令，直接编译会报“找不到 kernel 目录”或“Makefile 不存在”的错误。

步骤 4：验证编译环境（最小化编译测试）

在正式编译完整固件前，建议先执行一次 内核设备树编译 和 Buildroot 最小系统编译，以验证工具链和 SDK 源码的完整性。

cd ~/rk3568_sdk
# 加载板级配置（以 Firefly RK3568 为例）
source device/rockchip/.BoardConfig.mk
# 或者直接指定配置文件
export RK_BUILD_TARGET=Firefly-RK3568
# 第一步：仅编译内核设备树
./build.sh kernel -d rk3568-firefly-itx-3568jq 2>&1 | tee build_kernel.log
# 如果内核编译成功，会在 kernel/arch/arm64/boot/dts/rockchip/ 下生成 .dtb 文件
ls -la kernel/arch/arm64/boot/dts/rockchip/*.dtb

上述命令中，-d 参数指定设备树名称（不含 .dts 后缀）。编译成功后，会生成对应的 .dtb 文件。如果此步骤报错，请检查 build_kernel.log 中的具体错误信息，常见错误包括：缺少 lz4 工具、设备树源文件语法错误、头文件路径缺失等。

步骤 5：验证 Buildroot 工具链与根文件系统

# 进入 Buildroot 目录
cd buildroot
# 加载 Rockchip RK3568 默认配置
make rockchip_rk3568_defconfig
# 编译最小系统（仅编译工具链和 busybox，不编译完整 GUI）
make busybox -j$(nproc) 2>&1 | tee build_buildroot.log
# 验证输出
ls output/images/

如果 output/images/ 下生成了 rootfs.ext2 或 rootfs.tar.gz，说明 Buildroot 环境正常。注意，首次编译 Buildroot 需要下载源码包，耗时较长，建议使用国内镜像源（在 buildroot/.config 中修改 BR2_PRIMARY_SITE）。

2.3 案例拆解：一次典型的“工具链不匹配”故障排查

背景与约束：某开发团队在 Ubuntu 20.04 上使用 SDK v1.3.0，宿主机已安装官方工具链。在编译内核时，终端输出 aarch64-none-linux-gnu-gcc: command not found，但执行 aarch64-none-linux-gnu-gcc -v 却显示版本正常。

初始现象：编译脚本 build.sh 在调用内核 Makefile 时无法找到编译器。通过 echo $PATH 检查，发现 /opt/arm/gcc-arm-10.3-x86_64-aarch64-none-linux-gnu/bin 路径确实存在。

分析判断过程：我们怀疑是 build.sh 内部重置了 PATH 变量。查看 build.sh 脚本，发现其开头有 export PATH=/usr/bin:/bin:/usr/sbin:/sbin 的硬编码，覆盖了用户设置的 PATH。此外，脚本中使用了 CROSS_COMPILE 变量，但该变量在脚本内部被重新赋值为 aarch64-linux-gnu-（不带 none），而系统中并未安装该前缀的工具链。

实际操作步骤：

编辑 build.sh，注释掉强制重置 PATH 的行，或将其修改为 export PATH=$PATH:/opt/arm/.../bin。
在 build.sh 中查找 CROSS_COMPILE 赋值处，将其改为 aarch64-none-linux-gnu-。
重新执行 ./build.sh kernel，编译通过。

结果对比：修复前，编译在 5 秒内失败；修复后，内核编译耗时约 15 分钟（取决于 CPU 核心数），并成功生成 kernel.img。复盘经验：不要直接修改 SDK 顶层脚本，而应通过创建 device/rockchip/.BoardConfig.mk 中的自定义变量来覆盖默认值。例如，在板级配置文件中添加 export CROSS_COMPILE=aarch64-none-linux-gnu-，这样 build.sh 会优先读取该配置。

2.4 常见误区与总结复盘

误区/风险点	后果	正确做法
使用 root 用户编译	部分 Makefile 检查到 root 权限会拒绝执行，且污染系统环境	使用普通用户，并确保 `~/rk3568_sdk` 目录属主为当前用户
磁盘空间不足	编译过程中报 `No space left on device`，导致 `.o` 文件损坏	预留至少 200GB 空间，编译前执行 `df -h` 检查
忽略 `repo sync -l`	源码目录不完整，编译时提示缺少 `Makefile` 或 `Kconfig`	解压后立即执行本地恢复命令
工具链路径含中文或空格	GCC 无法解析路径，报 `invalid argument`	统一使用 `/opt/` 或 `/home/<user>/tools/` 等纯英文路径
未安装 `libssl-dev`	内核编译时无法生成 `certificates/signing_key.pem`，报 RSA 相关错误	确保 `libssl-dev` 已安装，或在内核配置中关闭 `CONFIG_MODULE_SIG`

总结复盘：搭建 RK3568 开发环境的核心在于“版本匹配”与“路径纯净”。版本匹配指 Ubuntu 版本、SDK 版本、工具链版本三者需在 Rockchip 官方支持矩阵内；路径纯净指所有工具链和 SDK 路径不得包含特殊字符。建议在编译前执行以下三连检查：

# 1. 检查工具链
aarch64-none-linux-gnu-gcc -v
# 2. 检查内核架构变量
echo $ARCH $CROSS_COMPILE
# 3. 检查 SDK 完整性
ls ~/rk3568_sdk/kernel/Makefile ~/rk3568_sdk/buildroot/Makefile