1. 为什么一个 hello 程序值得单独写一篇搞嵌入式开发的人都有一个共识环境搭好了项目就成功了一半。尤其是香橙派 5 这类 RK3588 平台性能强、接口多、NPU 算力也够看但它的开发体验和纯 PC 端完全不是一回事。你不可能把整个编译工具链、依赖库、源码全塞到板子上去跑板子的存储和内存再大也不适合干这种重活。所以交叉编译就成了绕不开的一环。这一篇要聊的就是交叉编译里最经典的那个起点——hello 程序。别看它只有几行代码它其实是整条工具链的“体检报告”。编译器能不能找到、sysroot 对不对、动态链接器路径有没有配错、生成的可执行文件架构是不是 aarch64全都能通过这一个 hello 暴露出来。我在带新人的时候从来不让他们一上来就去编 OpenCV 或者 FFmpeg而是先把这个 hello 跑通。因为一旦 hello 能编、能传、能在板子上跑起来后面编 yolov5s 的推理程序、编 Qt、编 ffmpeg 推流本质上都是同一套流程的放大版。这篇内容适合谁看如果你手上有一块香橙派 5 或者 5 Pro已经烧好了 Ubuntu 20.04 系统想开始做 RK3588 上的应用开发但卡在“怎么在电脑上编出板子能跑的程序”这一步那这篇就是给你写的。我会从工具链选型讲到实际编译、传输、运行把每一步背后的原因都讲清楚让你不只是抄命令而是真正理解交叉编译这件事。2. 交叉编译到底在解决什么问题2.1 本地编译和交叉编译的本质区别先把这个概念说透。本地编译就是你在什么机器上编译就在什么机器上运行。比如你在 x86 的 Ubuntu 上写个 C 程序gcc hello.c -o hello出来的hello就是 x86_64 架构的直接在本机跑没问题。交叉编译则是在一种架构的机器上编译出另一种架构能运行的程序。我们的开发机通常是 x86_64 的笔记本或者台式机而香橙派 5 的 RK3588 是 ARM 的 aarch64 架构。这两种架构的指令集完全不同x86 的编译器默认生成的是 x86 指令ARM 根本看不懂。所以我们需要一套专门的编译器它本身运行在 x86 上但生成的是 ARM 指令。这套东西就叫交叉编译工具链。你可以把它想象成翻译你是个只会中文的人x86 机器要写一封法文信ARM 程序给法国朋友香橙派看。你自己写不了法文但你手边有一本中法词典加一个懂法文的助手交叉编译工具链你负责表达逻辑助手负责翻译成法文。最终信是法文的法国朋友能读但写信的过程是在中文环境里完成的。2.2 为什么不用板子本地编译有人会问香橙派 5 性能不差啊RK3588 八核为什么不在板子上直接编译原因有几个。第一板子的存储和内存有限。编译一个稍微大点的项目中间文件动辄几个 G板子上的 eMMC 或者 TF 卡很容易就满了。热词里就有人提到“rk3588 刚烧写的 ubuntu20.04 磁盘就没空间了”这就是典型症状。第二编译速度慢。板子的 CPU 虽然核心多但主频和散热受限编一个大项目可能要几十分钟甚至几个小时而在 PC 上几分钟就搞定。第三工具链和依赖管理麻烦。PC 上装个包、换个版本很方便板子上折腾起来费时费力。所以交叉编译的核心价值就是借用 PC 的算力和存储产出板子能跑的程序。这是嵌入式开发的标准工作流不是可选项是必选项。2.3 RK3588 平台的特殊性RK3588 这颗芯片值得单独说两句。它是 8 核 big.LITTLE 架构4 个 A76 大核加 4 个 A55 小核GPU 是 Mali-G610还有 6 TOPS 算力的 NPU。香橙派 5 和 5 Pro 都用的这颗芯片。它的官方系统是 Ubuntu 20.04基于 aarch64 架构。这里有个细节要注意RK3588 的 Ubuntu 20.04 用的是 glibc 的某个特定版本。如果你在 PC 上用的交叉编译工具链自带的 glibc 版本比板子上的高编出来的程序在板子上跑就会报GLIBC_2.xx not found之类的错误。这是交叉编译里最常见的坑之一后面我会专门讲怎么排查。3. 工具链选型用哪个编译器3.1 三种常见选择给 RK3588 做交叉编译工具链大概有三个来源工具链来源特点适用场景官方 SDK 自带与板子系统完全匹配glibc 版本一致最稳妥推荐首选Linaro 官方工具链通用性强版本更新快通用 ARM 开发发行版仓库安装安装方便如gcc-aarch64-linux-gnu快速验证但版本可能不匹配我个人的建议是优先用香橙派官方 SDK 里的工具链。因为它是针对这块板子的系统专门配的glibc 版本、头文件、库路径都是对齐的能省掉一大堆兼容性问题。如果你只是想快速验证一下交叉编译流程用apt install gcc-aarch64-linux-gnu装一个也行但要注意版本匹配问题。3.2 工具链的目录结构不管你从哪弄来的工具链解压后大概都是这个结构gcc-arm-xxx-aarch64-linux-gnu/ ├── bin/ │ ├── aarch64-linux-gnu-gcc │ ├── aarch64-linux-gnu-g │ ├── aarch64-linux-gnu-ld │ └── ... ├── lib/ ├── include/ └── sysroot/关键在bin/目录里面那些aarch64-linux-gnu-开头的就是我们要用的工具。sysroot/目录里放的是目标系统的头文件和库编译时编译器会去这里找stdio.h之类的系统头文件。3.3 验证工具链是否可用解压完先别急着编先验证一下# 假设工具链解压在 /opt/toolchain/ export PATH/opt/toolchain/bin:$PATH # 检查版本 aarch64-linux-gnu-gcc -v如果能看到版本信息说明工具链本身没问题。如果报command not found那就是 PATH 没配对或者工具链的 bin 目录名字不对。有些工具链的前缀不是aarch64-linux-gnu-可能是aarch64-none-linux-gnu-或者别的具体看bin/目录里实际的文件名。提示把export PATH这行写进~/.bashrc省得每次开终端都要重新设。4. 动手写第一个 hello 程序4.1 源码就三行新建一个文件hello.c#include stdio.h int main(void) { printf(Hello from RK3588 aarch64!\n); return 0; }就这么简单。但就是这三行能验证整条工具链是否通畅。4.2 编译命令拆解编译命令看起来就一行但每个参数都有讲究aarch64-linux-gnu-gcc hello.c -o hello如果你用的是官方 SDK 的工具链可能还需要指定 sysrootaarch64-linux-gnu-gcc hello.c -o hello \ --sysroot/opt/toolchain/sysroot--sysroot的作用是告诉编译器目标系统的头文件和库在这个目录下别去用 PC 本机的。如果不指定编译器可能会混用 PC 的头文件编出来的程序在板子上跑就可能出问题。4.3 验证生成的文件架构编完之后第一件事是确认生成的hello是不是 ARM 架构的file hello正常输出应该是hello: ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV), dynamically linked, ...如果显示的是x86-64那说明你用的还是本机的 gcc不是交叉编译器。检查一下命令是不是写成了gcc而不是aarch64-linux-gnu-gcc。还可以用readelf看更详细的信息readelf -h hello | grep Machine应该输出Machine: AArch64。4.4 静态编译还是动态编译默认情况下上面的命令生成的是动态链接的可执行文件。它依赖板子上的libc.so.6等动态库。如果板子上的库版本和工具链的匹配那没问题。但如果不匹配就会报错。一个简单的规避方法是静态编译aarch64-linux-gnu-gcc hello.c -o hello_static -static静态编译会把所有依赖的库都打包进可执行文件体积会大一些几 MB但好处是不依赖板子上的库版本扔过去就能跑。对于 hello 这种小程序静态编译是个很好的验证手段。等确认流程通了再回头处理动态链接的版本匹配问题。注意静态编译不是万能的。如果程序里用了dlopen之类的动态加载机制静态编译会失效。而且静态编译的 glibc 在某些场景下会有兼容性问题。所以它适合验证不适合作为最终方案。5. 把程序传到板子上跑起来5.1 传输方式选择程序编好了怎么传到香橙派上常见的有这几种scp最简单一条命令搞定前提是板子和 PC 在同一网络U 盘适合没有网络的情况NFS 挂载适合频繁传输调试串口传输速度慢一般不用最常用的还是 scpscp hello root192.168.1.100:/root/把192.168.1.100换成你板子的实际 IP。传完之后在板子上chmod x hello加上执行权限然后./hello运行。5.2 运行报错怎么办如果运行时报No such file or directory但文件明明在那里这通常是动态链接器路径不对。用readelf看一下readelf -l hello | grep interpreter输出可能是[Requesting program interpreter: /lib/ld-linux-aarch64.so.1]。如果板子上这个路径下没有对应的文件就会报这个错。解决办法是检查板子上的动态链接器实际路径或者改用静态编译。如果报GLIBC_2.xx not found那就是工具链的 glibc 版本比板子上的高。解决办法是换用和板子系统匹配的工具链或者降低工具链版本。5.3 一个完整的验证流程把上面的步骤串起来一个完整的验证流程是这样的# 1. 设置工具链路径 export PATH/opt/toolchain/bin:$PATH # 2. 编译 aarch64-linux-gnu-gcc hello.c -o hello --sysroot/opt/toolchain/sysroot # 3. 验证架构 file hello # 4. 传输 scp hello root192.168.1.100:/root/ # 5. 在板子上运行 ssh root192.168.1.100 chmod x /root/hello /root/hello如果最后能看到Hello from RK3588 aarch64!恭喜你交叉编译环境通了。接下来编 yolov5s 的推理程序、编 Qt、编 ffmpeg都是在这个基础上扩展。6. 常见问题与排查技巧6.1 问题速查表现象可能原因解决办法command not foundPATH 没配检查工具链 bin 目录并加入 PATH生成的是 x86 程序用了本机 gcc确认命令前缀是aarch64-linux-gnu-GLIBC_2.xx not foundglibc 版本不匹配换用匹配的工具链或静态编译No such file or directory动态链接器路径不对检查 interpreter 路径或静态编译传输后无法执行没有执行权限chmod x编译报头文件找不到sysroot 没指定加--sysroot参数6.2 几个容易踩的坑第一个坑工具链版本和板子系统不匹配。这是最常见的。香橙派 5 的 Ubuntu 20.04 自带的 glibc 版本是固定的如果你从网上下了一个最新版的 Linaro 工具链它自带的 glibc 可能比板子上的新编出来的程序就跑不了。解决办法是用官方 SDK 的工具链或者用strings命令查一下板子上 glibc 的版本然后找对应版本的工具链。第二个坑sysroot 路径写错。有些工具链的 sysroot 不在工具链根目录下而是在aarch64-linux-gnu/libc/之类的子目录里。指定错了会导致头文件找不到或者混用了 PC 的头文件。建议先用find找一下stdio.h在哪确认 sysroot 的实际路径。第三个坑动态库路径问题。即使 glibc 版本匹配如果你的程序依赖了其他动态库比如 OpenCV这些库也需要交叉编译好并放到板子上。而且板子上的LD_LIBRARY_PATH要包含这些库的路径。这个在编 hello 的时候不会遇到但后面编复杂项目一定会遇到提前有个心理准备。第四个坑文件系统权限。从 PC 传过去的文件权限可能不对。尤其是用 U 盘拷贝的时候FAT32 格式不支持 Linux 的权限位拷过去可能没有执行权限。记得chmod x。6.3 一个实用的调试技巧如果程序在板子上跑不起来又看不出原因可以用strace跟踪一下strace ./hello它会打印出程序执行过程中的所有系统调用能看到它到底卡在哪一步、找不到哪个文件。这个工具在排查动态链接问题时特别好用。7. 从 hello 到 yolov5s 的扩展思路hello 跑通了接下来就是把它扩展成真正的项目。以 yolov5s 为例交叉编译的流程会复杂很多但核心逻辑是一样的准备依赖库yolov5s 推理需要 OpenCV、RKNN Runtime 等库这些库都需要交叉编译成 aarch64 版本配置编译选项在 CMake 或 Makefile 里指定交叉编译器、sysroot、依赖库路径编译主程序把 yolov5s 的推理代码和依赖库链接起来部署到板子把可执行文件和所有依赖的动态库一起传到板子上设置运行环境配置LD_LIBRARY_PATH确保板子能找到所有依赖库这个过程里hello 验证过的工具链、sysroot、传输方式、运行环境全都会用到。所以别小看这个 hello它是整条链路的最小验证单元。我个人在实际操作中的体会是交叉编译的问题90% 都出在环境配置上而不是代码本身。工具链版本、sysroot 路径、动态库依赖这三样东西对齐了后面就是一马平川。所以每次开始一个新项目我都会先花十分钟编一个 hello 验证环境确认没问题了再动手写业务代码。这个习惯帮我省了无数排查环境问题的时间。最后再分享一个小技巧把工具链的 PATH 设置、sysroot 路径、常用的编译命令写成一个env.sh脚本每次开终端先source env.sh。这样既不会忘记配置也方便在不同项目之间切换工具链。
