告别手动复制在 Buildroot 中添加自己的 ARM64 软件包上一篇我们在 QEMU 启动的 ARM64 Linux 中通过 gdbserver 和 Buildroot 交叉 GDB 调试了一个 C 程序。当时需要手动交叉编译debug_demo复制到 rootfs overlay再生成镜像。程序能运行了但每次修改源码仍要记得重新编译和复制。这一篇把同一个程序做成 Buildroot 软件包由 Buildroot 读取源码、调用交叉编译器并安装到镜像中的/usr/bin/debug_demo。重点不只是第一次运行成功还要验证修改源码后重建软件包和镜像QEMU 就能运行新版本不再手动复制可执行文件。实验说明本文基于 Ubuntu 20.04、Buildroot 2025.02.8 和 QEMU ARM64 环境已完成自定义软件包启用、ARM64 产物检查、首次运行以及修改源码后的重建更新验证。文中保留了实际终端记录GDB 延伸调试不属于本篇已验证范围。系列阅读顺序《没有开发板也能学嵌入式 LinuxUbuntu 20.04 QEMU Buildroot 跑通 ARM64》搭建环境、启动系统并运行 Hello World。《没有开发板也能调试 ARM64 程序QEMU GDB 远程调试实战》准备数组求和程序完成远程调试。本篇把程序纳入 Buildroot 软件包构建流程。如果还没有可启动的 QEMU ARM64 系统请先完成第一篇本文沿用前两篇的实验目录和配置不从零搭建环境。一、这次要完成什么本次实验的流程debug_demo.c - Buildroot 自定义包 - 自动交叉编译 - 安装到目标文件系统 - 生成 rootfs 镜像 - QEMU 中运行 /usr/bin/debug_demo具体检查三个结果menuconfig中能找到并启用debug-demo。生成的镜像包含/usr/bin/debug_demo运行后输出total 100。修改源码并重建后新镜像输出更新后的内容不需要手动复制可执行文件。这里的“软件包”是Buildroot 的构建单元不是在目标系统中使用apt install安装的.deb包。二、准备环境保留已有配置项目本文使用的环境开发主机Ubuntu 20.04 x86_64 虚拟机Buildroot2025.02.8Buildroot 源码目录~/buildroot-2025.02.8基础配置qemu_aarch64_virt_defconfig已按前文调整目标系统QEMU ARM64 LinuxQEMU 可执行文件/usr/bin/qemu-system-aarch64自定义目录~/buildroot-external-demo包名debug-demo目标程序路径/usr/bin/debug_demo沿用前两篇已经能启动的系统和交叉工具链不更换工具链。原有的 GDB、gdbserver 和 overlay 配置可以保留。默认在 Ubuntu 主机执行命令标注“QEMU 目标端”的命令才在 ARM64 Linux 内执行。文中的 Bash 命令不适用于 Windows PowerShell。如果 QEMU 仍在运行先在目标端执行poweroff等待系统关机。如果 QEMU 没有退出再按CtrlA松开后按X。确认 QEMU 已退出后再重新生成镜像。不要同时启动两个使用同一个可写 rootfs 镜像的 QEMU也不要在 QEMU 使用镜像时从主机挂载它。在 Ubuntu 主机中备份当前配置cd~/buildroot-2025.02.8cp-p.config.config.before-debug-demo.$(date%Y%m%d-%H%M%S)本文是在当前.config上增加一个应用包不要重新执行make qemu_aarch64_virt_defconfig否则会重置之前调整过的配置。也不需要为了添加这个简单 C 程序执行make clean或make distclean。本文不改变架构、C 库或工具链配置。如果已经执行了make clean只要原.config和源码仍在就可以按原配置重新构建工具链和镜像都会重新生成耗时会更长。单独放进旧镜像或output/的文件不会自动恢复。若已接入外部包重建时显式传入BR2_EXTERNAL路径。三、创建外部包目录使用BR2_EXTERNAL把自定义源码和包规则放到 Buildroot 目录之外不修改官方源码树。下面是完成第三至六节后的目录结构示意现在不需要手动创建其中的所有文件/home/embed/ |-- buildroot-2025.02.8/ | |-- .config | -- output/ -- buildroot-external-demo/ |-- external.desc |-- Config.in |-- external.mk |-- package/ | -- debug-demo/ | |-- Config.in | -- debug-demo.mk -- src/ -- debug-demo/ -- debug_demo.cBR2_EXTERNAL用于加载自定义配置和包规则不是菜单中的External toolchain。升级 Buildroot 时可以保留这个目录但仍需验证兼容性。先在 Ubuntu 中创建目录mkdir-p~/buildroot-external-demo/package/debug-demomkdir-p~/buildroot-external-demo/src/debug-democd~/buildroot-external-demo以下命令会写入示例文件。如果这些路径已经有你自己的内容先备份不要直接覆盖。新建文件建议使用 UTF-8 和 LF 换行。四、准备程序源码继续使用上一篇的数组求和程序不增加新的业务逻辑。确认当前位于~/buildroot-external-demo在 Ubuntu 主机终端中完整复制执行下面的代码块从cat一直到最后一行EOF。它会创建源文件并写入代码不需要再手动新建文件。catsrc/debug-demo/debug_demo.cEOF #include stdio.h int compute_total(const int *values, int count) { int total 0; for (int index 0; index count; index) { total values[index]; } return total; } int main(void) { const int values[] {10, 20, 30, 40}; int result compute_total(values, 4); printf(total %d\n, result); return 0; } EOF后续始终修改这个源文件不修改output/build/下的临时副本。本例只有一个 C 文件直接由包规则调用编译器不另写应用 Makefile。五、让 Buildroot 认识这个外部目录1. external.desc定义外部目录的名字仍在~/buildroot-external-demo中执行catexternal.descEOF name: ARM64_DEMO desc: ARM64 tutorial packages EOFname只能使用英文字母、数字和下划线。这里的ARM64_DEMO是给外部目录起的标识名不是目录路径。第七节会通过BR2_EXTERNAL$HOME/buildroot-external-demo告诉 Buildroot 外部目录的位置。Buildroot 再读取该目录的external.desc根据name自动提供变量命名格式为BR2_EXTERNAL_name_PATH。变量名中的ARM64_DEMO来自name变量值来自BR2_EXTERNAL指定的目录不是根据名字猜出路径。本例中Ubuntu 用户的$HOME是/home/embed所以对应关系是external.desc 中的名字ARM64_DEMO 自动提供的变量名 BR2_EXTERNAL_ARM64_DEMO_PATH 变量代表的完整路径 /home/embed/buildroot-external-demo因此后面的 Makefile 中$(BR2_EXTERNAL_ARM64_DEMO_PATH)/src/debug-demo就指向/home/embed/buildroot-external-demo/src/debug-demo。这样不用把主机路径写死在规则中目录换位置后重新通过BR2_EXTERNAL指定新路径即可。这是机制说明不需要额外执行命令也不需要手动创建或export这个变量。下一步继续创建顶层Config.in。2. 顶层 Config.in注册软件包菜单catConfig.inEOF source $BR2_EXTERNAL_ARM64_DEMO_PATH/package/debug-demo/Config.in EOF它负责把我们定义的软件包选项接入 Buildroot 的配置菜单。这里引用的package/debug-demo/Config.in会在第六节创建完成所有文件后再打开menuconfig。3. external.mk加载软件包构建规则catexternal.mkEOF include $(sort $(wildcard $(BR2_EXTERNAL_ARM64_DEMO_PATH)/package/*/*.mk)) EOF它负责加载外部package/目录下的软件包.mk文件。保留命令中的EOF单引号避免 Bash 提前展开本应由 Buildroot 解析的变量。六、编写 debug-demo 软件包以下文件创建命令仍在 Ubuntu 主机的~/buildroot-external-demo目录中执行。1. 软件包 Config.incatpackage/debug-demo/Config.inEOF config BR2_PACKAGE_DEBUG_DEMO bool debug-demo help A small C program that computes an array total. EOFBR2_PACKAGE_DEBUG_DEMO是配置符号debug-demo是菜单里显示的名称。默认不启用需要我们手动勾选。本例只使用标准 C不需要新增 C 或第三方库依赖。实际编译架构由当前 Buildroot 配置决定。2. 软件包 debug-demo.mkcatpackage/debug-demo/debug-demo.mkEOF DEBUG_DEMO_VERSION 1.0 DEBUG_DEMO_SITE $(BR2_EXTERNAL_ARM64_DEMO_PATH)/src/debug-demo DEBUG_DEMO_SITE_METHOD local define DEBUG_DEMO_BUILD_CMDS $(TARGET_CC) $(TARGET_CFLAGS) -Wall -Wextra -O0 -g -gdwarf-4 \ -fno-omit-frame-pointer $(D)/debug_demo.c \ -o $(D)/debug_demo $(TARGET_LDFLAGS) endef define DEBUG_DEMO_INSTALL_TARGET_CMDS $(INSTALL) -D -m 0755 $(D)/debug_demo \ $(TARGET_DIR)/usr/bin/debug_demo endef $(eval $(generic-package)) EOF注意define块中的命令以Tab缩进。复制后如果编辑器把它变成了空格建议检查并恢复。包规则的核心内容如下内容作用DEBUG_DEMO_VERSION定义示例包版本不代表自动监测源码变化DEBUG_DEMO_SITE指定主机上的源码目录DEBUG_DEMO_SITE_METHOD local使用本地源码不为本包下载网络源码$(TARGET_CC)使用当前 Buildroot 配置对应的交叉编译器$(TARGET_CFLAGS)/$(TARGET_LDFLAGS)继承目标编译和链接参数$(D)当前软件包的构建目录$(TARGET_DIR)目标文件系统的安装目录$(eval $(generic-package))调用通用包基础设施生成构建和安装目标关键区别是编译器不再写死路径安装也不再依赖手动复制。$(TARGET_CC)和$(TARGET_DIR)都由 Buildroot 提供。命名保持对应包名和 make 目标为debug-demo配置符号为BR2_PACKAGE_DEBUG_DEMO变量前缀为DEBUG_DEMO_。可执行文件名debug_demo可以与包名不同。编译参数保留了上一篇的调试设置符号裁剪和许可证元数据放在文末补充说明中不影响本篇主线。七、加载外部目录并启用软件包回到 Buildroot 源码目录cd~/buildroot-2025.02.8makeBR2_EXTERNAL$HOME/buildroot-external-demomenuconfig本文假设此前没有使用其他外部目录。如果你已经设置了BR2_EXTERNAL应保留原有目录并把新目录追加到同一个带引号、空格分隔的路径列表中不要直接替换。在顶层找到External options进入本文的外部包菜单并勾选External options ARM64 tutorial packages [*] debug-demo上面是示意层级实际菜单可能把描述显示为提示行。也可以按/搜索BR2_PACKAGE_DEBUG_DEMO定位选项。保存并退出检查grep^BR2_PACKAGE_DEBUG_DEMO.config本次保存配置后的实际检查结果如下说明debug-demo已启用但此时还没有构建它embedembedtest:~/buildroot-2025.02.8$ grep ^BR2_PACKAGE_DEBUG_DEMO .config BR2_PACKAGE_DEBUG_DEMOyBuildroot 会把外部目录路径记录在输出目录的.br2-external.mk中本文为output/.br2-external.mk因此后续通常可以直接执行make debug-demo或make。换用新输出目录或相关记录被清理后要重新传入BR2_EXTERNAL仅备份.config并不包含这项路径记录。八、迁移说明移走旧 overlay 程序如果没有做过上一篇的 overlay 部署可以跳过本节。上一篇的rootfs-overlay/root/debug_demo对应目标端/root/debug_demo本篇则安装到/usr/bin/debug_demo。为避免误运行旧文件先把旧程序备份到 overlay 之外cd~/buildroot-2025.02.8mkdir-p~/debug-demo-backupif[-frootfs-overlay/root/debug_demo];thenmvrootfs-overlay/root/debug_demo\$HOME/debug-demo-backup/debug_demo.overlay.$(date%Y%m%d-%H%M%S)fi还要注意从 overlay 删除文件不会自动删除已经复制到output/target/的旧副本。在确认它就是前文的实验程序之后可做一次针对性的迁移清理rm-foutput/target/root/debug_demo这是一次性清理不是日常安装方式。不要删除整个output/target/原 overlay 配置和其他静态文件继续保留。已执行make clean时旧目标副本已被清理但 overlay 中的旧源文件仍需移走。如果其他已配置的 overlay 也包含usr/bin/debug_demo要先移走同名文件。overlay 在包安装之后复制到目标文件系统同一路径的旧文件可能覆盖新包产物。九、构建软件包再生成镜像1. 先单独构建这个包Ubuntu 主机执行cd~/buildroot-2025.02.8makedebug-demoV1echo$?echo $?要紧接着构建命令执行。只有返回0才继续后面的检查。V1显示实际命令便于检查源码同步、交叉编译和安装过程。检查安装结果ls-loutput/target/usr/bin/debug_demofileoutput/target/usr/bin/debug_demo重点看file输出是否包含ELF 64-bit和ARM aarch64不要把文件大小、完整 ELF 描述或时间戳当成固定值。不要直接在 Ubuntu x86_64 主机执行这个 ARM64 程序来验证运行结果。运行验证放到 QEMU 目标端。本次在 Ubuntu 主机上的文件检查结果如下不是执行 ARM64 程序的结果embedembedtest:~/buildroot-2025.02.8$ ls -l output/target/usr/bin/debug_demo -rwxr-xr-x 1 embed embed 10824 Oct 15 05:32 output/target/usr/bin/debug_demo embedembedtest:~/buildroot-2025.02.8$ file output/target/usr/bin/debug_demo output/target/usr/bin/debug_demo: ELF 64-bit LSB shared object, ARM aarch64, version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-aarch64.so.1, for GNU/Linux 6.12.0, with debug_info, not stripped其中ARM aarch64表明产物的目标架构正确with debug_info, not stripped表明此时的文件包含调试信息、尚未裁剪符号。后续生成镜像时仍可能裁剪不能据此断定镜像内的程序也保留了调试信息。2. 重新生成 rootfs 镜像make debug-demo只构建并安装软件包不会重新生成 rootfs 镜像。继续执行完整构建目标make-j2echo$?确认返回0后检查镜像ls-lhoutput/images/Image output/images/rootfs.ext2沿用前文的-j2写法不额外启用实验性的顶层并行构建选项也不要同时运行两条操作同一输出目录的构建命令。十、启动 QEMU运行镜像里的程序确认上一节完整构建成功、旧 QEMU 已退出再在 Ubuntu 主机的 Buildroot 源码目录中启动cd~/buildroot-2025.02.8 /usr/bin/qemu-system-aarch64\-Mvirt\-cpucortex-a53\-smp2\-m1G\-nographic\-kerneloutput/images/Image\-appendrootwait root/dev/vda consolettyAMA0\-drivefileoutput/images/rootfs.ext2,ifnone,formatraw,idhd0\-devicevirtio-blk-device,drivehd0\-netdevuser,idnet0,hostfwdtcp:127.0.0.1:5000-:2345\-devicevirtio-net-device,netdevnet0网络配置沿用上一篇保留本机回环地址上的 GDB 端口转发。本篇直接运行程序不依赖远程调试连接。进入目标系统并以root登录后在QEMU 目标端执行ls-l/usr/bin/debug_demo /usr/bin/debug_demoecho$?使用绝对路径是为了明确运行的是本篇软件包安装的程序而不是遗留的/root/debug_demo。这次启动后不再向目标系统传输或复制程序。本次 QEMU 目标端的实际运行记录如下# ls -l /usr/bin/debug_demo -rwxr-xr-x 1 root root 5920 Oct 15 05:34 /usr/bin/debug_demo # /usr/bin/debug_demo total 100 # echo $? 0这说明程序已经随 rootfs 镜像进入目标系统运行后输出total 100并正常退出。接下来还需通过第十一节验证修改外部源码后重建软件包和镜像能否带入新版本。十一、关键验证修改源码后不再手动复制首次输出total 100只证明程序进入了镜像。接下来用一个可见的输出变化检查“源码修改到镜像更新”的整条流程。1. 关闭 QEMU修改外部源码先在 QEMU 目标端执行poweroff。等待系统关机如果 QEMU 没有退出再按CtrlA松开后按X。确认 QEMU 已退出后再继续。在 Ubuntu 中编辑~/buildroot-external-demo/src/debug-demo/debug_demo.c找到原来的printf(total %d\n, result);只把这一行改为下面的内容然后保存文件printf(debug-demo package v2: total %d\n,result);这里的v2只是用于区分输出的测试标记不需要把包规则中的DEBUG_DEMO_VERSION 1.0改成 2.0。修改的是外部目录中的源文件不是output/build/下的副本。2. 重建软件包在 Ubuntu 主机中执行重新同步源码、编译并安装软件包cd~/buildroot-2025.02.8makedebug-demo-rebuildV1echo$?紧接着查看的返回码应为0否则先处理构建错误不继续生成镜像。在 Buildroot 2025.02.8 中本例的SITE_METHOD local使用本地源码同步机制。debug-demo-rebuild会重新同步外部源码触发编译并把新程序安装到output/target/usr/bin/debug_demo但不会更新 rootfs 镜像。仅修改本地源码后执行普通make不要期待 Buildroot 自动发现并重编译已经完成的软件包。3. 重新生成镜像继续在 Buildroot 源码目录中执行make-j2echo$?返回码为0后再启动 QEMU。这里的完整make用于把更新后的目标文件系统重新生成为镜像不是要求清理后重编译整套工具链。4. 启动新镜像核对输出使用第十节的命令重新启动 QEMU仍使用刚生成的output/images/rootfs.ext2。以root登录后在目标端执行/usr/bin/debug_demoecho$?echo $?要紧接着程序执行正常退出时应返回0。本次保存的目标端记录如下仅展示了新版输出没有记录这次的退出码# /usr/bin/debug_demo debug-demo package v2: total 100相比首次运行多出了debug-demo package v2:标记说明源码修改已进入新镜像。这次验证的关键是不手动调用交叉编译器也不手动执行cp或install部署可执行文件编译和安装由 Buildroot 的包规则完成。十二、遇到问题时检查哪里1. menuconfig 中找不到 debug-demo检查外部目录的三个入口文件是否齐全顶层Config.in的source路径是否正确以及external.desc中的ARM64_DEMO是否与路径变量一致。然后用第七节的命令显式指定BR2_EXTERNAL打开菜单。2. 提示找不到 debug_demo.c检查源码目录和文件是否存在ls-l~/buildroot-external-demo/src/debug-demo/debug_demo.cDEBUG_DEMO_SITE指向的是包含源码的目录不是 C 文件本身。还要检查拼写包目录使用debug-demo源码文件使用debug_demo.c。3. 单包构建成功QEMU 里却没有程序确认.config中存在BR2_PACKAGE_DEBUG_DEMOy单包构建后执行过完整make并且 QEMU 启动的是新生成的output/images/rootfs.ext2。4. 修改了源码运行结果仍是旧版本依次检查修改的是不是外部源码、是否执行debug-demo-rebuild、是否更新镜像并重启 QEMU、运行路径是否为/usr/bin/debug_demo以及 overlay 是否覆盖了同路径文件。如果删除过源文件、调整过构建规则或怀疑构建目录有残留可先清理本包makedebug-demo-dircleanecho$?返回0后再执行make -j2并检查返回码。它会重新构建已启用的包和镜像不删除外部源码也不会重建已有的整套工具链。十三、补充说明overlay 和软件包各管什么overlay 适合配置文件、脚本等静态内容不负责把 C 源码编译成程序需要编译的应用交给包规则避免两者管理同一目标路径。还能继续用 GDB 吗可以但 Buildroot 可能裁剪目标端程序的符号。主机 GDB 应加载本次包构建目录中未裁剪、包含调试信息的可执行文件目标端运行/usr/bin/debug_demo。两者必须来自同一次编译不能继续使用以前手动编译的旧符号文件。这条延伸调试路径尚未实测。取消勾选等于卸载吗不等于。Buildroot 不会自动清除旧安装文件dirclean也只清理本包构建目录。需要完全不含该包的干净镜像时应备份配置和自定义文件后进行完整重建。许可证怎么填写本例未指定DEBUG_DEMO_LICENSE许可证字段会显示为unknown也未提供DEBUG_DEMO_LICENSE_FILES。正式维护或分发前应按实际授权补齐不能因为使用 Buildroot 就直接把应用声明为 GPL 或 MIT。这些字段只是 Buildroot 的许可证元数据不能代替实际授权也不能证明代码权属。使用或分发第三方代码时仍须遵守其许可证要求不要把unknown理解为“没有授权限制”。本文讲解构建方法不要求博客或独立应用仅因使用 Buildroot 就采用 GPL。若另行发布源码包、工具链或系统镜像则需按其中各组件的实际许可证检查相应义务不能只看本例软件包的许可证字段。十四、小结本篇要完成的变化是之前手动编译 - 手动复制程序 - 生成镜像 现在维护源码和包规则 - Buildroot 编译并安装 - 生成镜像日常修改时记住两个动作make debug-demo-rebuild更新应用完整make更新镜像。不再手动复制程序但也不能期待普通make自动发现所有本地源码变化。这一篇把应用纳入构建流程。后续可以继续把实验配置保存为自己的 defconfig并管理 overlay 和启动脚本让整套 QEMU 实验环境更容易重新生成。参考资料Buildroot 官方手册外部目录、通用包基础设施、单包重建与文件系统定制。在线手册会随版本更新实验时也应对照 2025.02.8 源码树中的docs/manual/。Buildroot 2025.02.8 的通用包实现本地源码同步和 rebuild 目标的版本对应实现。
告别手动复制在 Buildroot 中添加自己的 ARM64 软件包上一篇我们在 QEMU 启动的 ARM64 Linux 中通过 gdbserver 和 Buildroot 交叉 GDB 调试了一个 C 程序。当时需要手动交叉编译debug_demo复制到 rootfs overlay再生成镜像。程序能运行了但每次修改源码仍要记得重新编译和复制。这一篇把同一个程序做成 Buildroot 软件包由 Buildroot 读取源码、调用交叉编译器并安装到镜像中的/usr/bin/debug_demo。重点不只是第一次运行成功还要验证修改源码后重建软件包和镜像QEMU 就能运行新版本不再手动复制可执行文件。实验说明本文基于 Ubuntu 20.04、Buildroot 2025.02.8 和 QEMU ARM64 环境已完成自定义软件包启用、ARM64 产物检查、首次运行以及修改源码后的重建更新验证。文中保留了实际终端记录GDB 延伸调试不属于本篇已验证范围。系列阅读顺序《没有开发板也能学嵌入式 LinuxUbuntu 20.04 QEMU Buildroot 跑通 ARM64》搭建环境、启动系统并运行 Hello World。《没有开发板也能调试 ARM64 程序QEMU GDB 远程调试实战》准备数组求和程序完成远程调试。本篇把程序纳入 Buildroot 软件包构建流程。如果还没有可启动的 QEMU ARM64 系统请先完成第一篇本文沿用前两篇的实验目录和配置不从零搭建环境。一、这次要完成什么本次实验的流程debug_demo.c - Buildroot 自定义包 - 自动交叉编译 - 安装到目标文件系统 - 生成 rootfs 镜像 - QEMU 中运行 /usr/bin/debug_demo具体检查三个结果menuconfig中能找到并启用debug-demo。生成的镜像包含/usr/bin/debug_demo运行后输出total 100。修改源码并重建后新镜像输出更新后的内容不需要手动复制可执行文件。这里的“软件包”是Buildroot 的构建单元不是在目标系统中使用apt install安装的.deb包。二、准备环境保留已有配置项目本文使用的环境开发主机Ubuntu 20.04 x86_64 虚拟机Buildroot2025.02.8Buildroot 源码目录~/buildroot-2025.02.8基础配置qemu_aarch64_virt_defconfig已按前文调整目标系统QEMU ARM64 LinuxQEMU 可执行文件/usr/bin/qemu-system-aarch64自定义目录~/buildroot-external-demo包名debug-demo目标程序路径/usr/bin/debug_demo沿用前两篇已经能启动的系统和交叉工具链不更换工具链。原有的 GDB、gdbserver 和 overlay 配置可以保留。默认在 Ubuntu 主机执行命令标注“QEMU 目标端”的命令才在 ARM64 Linux 内执行。文中的 Bash 命令不适用于 Windows PowerShell。如果 QEMU 仍在运行先在目标端执行poweroff等待系统关机。如果 QEMU 没有退出再按CtrlA松开后按X。确认 QEMU 已退出后再重新生成镜像。不要同时启动两个使用同一个可写 rootfs 镜像的 QEMU也不要在 QEMU 使用镜像时从主机挂载它。在 Ubuntu 主机中备份当前配置cd~/buildroot-2025.02.8cp-p.config.config.before-debug-demo.$(date%Y%m%d-%H%M%S)本文是在当前.config上增加一个应用包不要重新执行make qemu_aarch64_virt_defconfig否则会重置之前调整过的配置。也不需要为了添加这个简单 C 程序执行make clean或make distclean。本文不改变架构、C 库或工具链配置。如果已经执行了make clean只要原.config和源码仍在就可以按原配置重新构建工具链和镜像都会重新生成耗时会更长。单独放进旧镜像或output/的文件不会自动恢复。若已接入外部包重建时显式传入BR2_EXTERNAL路径。三、创建外部包目录使用BR2_EXTERNAL把自定义源码和包规则放到 Buildroot 目录之外不修改官方源码树。下面是完成第三至六节后的目录结构示意现在不需要手动创建其中的所有文件/home/embed/ |-- buildroot-2025.02.8/ | |-- .config | -- output/ -- buildroot-external-demo/ |-- external.desc |-- Config.in |-- external.mk |-- package/ | -- debug-demo/ | |-- Config.in | -- debug-demo.mk -- src/ -- debug-demo/ -- debug_demo.cBR2_EXTERNAL用于加载自定义配置和包规则不是菜单中的External toolchain。升级 Buildroot 时可以保留这个目录但仍需验证兼容性。先在 Ubuntu 中创建目录mkdir-p~/buildroot-external-demo/package/debug-demomkdir-p~/buildroot-external-demo/src/debug-democd~/buildroot-external-demo以下命令会写入示例文件。如果这些路径已经有你自己的内容先备份不要直接覆盖。新建文件建议使用 UTF-8 和 LF 换行。四、准备程序源码继续使用上一篇的数组求和程序不增加新的业务逻辑。确认当前位于~/buildroot-external-demo在 Ubuntu 主机终端中完整复制执行下面的代码块从cat一直到最后一行EOF。它会创建源文件并写入代码不需要再手动新建文件。catsrc/debug-demo/debug_demo.cEOF #include stdio.h int compute_total(const int *values, int count) { int total 0; for (int index 0; index count; index) { total values[index]; } return total; } int main(void) { const int values[] {10, 20, 30, 40}; int result compute_total(values, 4); printf(total %d\n, result); return 0; } EOF后续始终修改这个源文件不修改output/build/下的临时副本。本例只有一个 C 文件直接由包规则调用编译器不另写应用 Makefile。五、让 Buildroot 认识这个外部目录1. external.desc定义外部目录的名字仍在~/buildroot-external-demo中执行catexternal.descEOF name: ARM64_DEMO desc: ARM64 tutorial packages EOFname只能使用英文字母、数字和下划线。这里的ARM64_DEMO是给外部目录起的标识名不是目录路径。第七节会通过BR2_EXTERNAL$HOME/buildroot-external-demo告诉 Buildroot 外部目录的位置。Buildroot 再读取该目录的external.desc根据name自动提供变量命名格式为BR2_EXTERNAL_name_PATH。变量名中的ARM64_DEMO来自name变量值来自BR2_EXTERNAL指定的目录不是根据名字猜出路径。本例中Ubuntu 用户的$HOME是/home/embed所以对应关系是external.desc 中的名字ARM64_DEMO 自动提供的变量名 BR2_EXTERNAL_ARM64_DEMO_PATH 变量代表的完整路径 /home/embed/buildroot-external-demo因此后面的 Makefile 中$(BR2_EXTERNAL_ARM64_DEMO_PATH)/src/debug-demo就指向/home/embed/buildroot-external-demo/src/debug-demo。这样不用把主机路径写死在规则中目录换位置后重新通过BR2_EXTERNAL指定新路径即可。这是机制说明不需要额外执行命令也不需要手动创建或export这个变量。下一步继续创建顶层Config.in。2. 顶层 Config.in注册软件包菜单catConfig.inEOF source $BR2_EXTERNAL_ARM64_DEMO_PATH/package/debug-demo/Config.in EOF它负责把我们定义的软件包选项接入 Buildroot 的配置菜单。这里引用的package/debug-demo/Config.in会在第六节创建完成所有文件后再打开menuconfig。3. external.mk加载软件包构建规则catexternal.mkEOF include $(sort $(wildcard $(BR2_EXTERNAL_ARM64_DEMO_PATH)/package/*/*.mk)) EOF它负责加载外部package/目录下的软件包.mk文件。保留命令中的EOF单引号避免 Bash 提前展开本应由 Buildroot 解析的变量。六、编写 debug-demo 软件包以下文件创建命令仍在 Ubuntu 主机的~/buildroot-external-demo目录中执行。1. 软件包 Config.incatpackage/debug-demo/Config.inEOF config BR2_PACKAGE_DEBUG_DEMO bool debug-demo help A small C program that computes an array total. EOFBR2_PACKAGE_DEBUG_DEMO是配置符号debug-demo是菜单里显示的名称。默认不启用需要我们手动勾选。本例只使用标准 C不需要新增 C 或第三方库依赖。实际编译架构由当前 Buildroot 配置决定。2. 软件包 debug-demo.mkcatpackage/debug-demo/debug-demo.mkEOF DEBUG_DEMO_VERSION 1.0 DEBUG_DEMO_SITE $(BR2_EXTERNAL_ARM64_DEMO_PATH)/src/debug-demo DEBUG_DEMO_SITE_METHOD local define DEBUG_DEMO_BUILD_CMDS $(TARGET_CC) $(TARGET_CFLAGS) -Wall -Wextra -O0 -g -gdwarf-4 \ -fno-omit-frame-pointer $(D)/debug_demo.c \ -o $(D)/debug_demo $(TARGET_LDFLAGS) endef define DEBUG_DEMO_INSTALL_TARGET_CMDS $(INSTALL) -D -m 0755 $(D)/debug_demo \ $(TARGET_DIR)/usr/bin/debug_demo endef $(eval $(generic-package)) EOF注意define块中的命令以Tab缩进。复制后如果编辑器把它变成了空格建议检查并恢复。包规则的核心内容如下内容作用DEBUG_DEMO_VERSION定义示例包版本不代表自动监测源码变化DEBUG_DEMO_SITE指定主机上的源码目录DEBUG_DEMO_SITE_METHOD local使用本地源码不为本包下载网络源码$(TARGET_CC)使用当前 Buildroot 配置对应的交叉编译器$(TARGET_CFLAGS)/$(TARGET_LDFLAGS)继承目标编译和链接参数$(D)当前软件包的构建目录$(TARGET_DIR)目标文件系统的安装目录$(eval $(generic-package))调用通用包基础设施生成构建和安装目标关键区别是编译器不再写死路径安装也不再依赖手动复制。$(TARGET_CC)和$(TARGET_DIR)都由 Buildroot 提供。命名保持对应包名和 make 目标为debug-demo配置符号为BR2_PACKAGE_DEBUG_DEMO变量前缀为DEBUG_DEMO_。可执行文件名debug_demo可以与包名不同。编译参数保留了上一篇的调试设置符号裁剪和许可证元数据放在文末补充说明中不影响本篇主线。七、加载外部目录并启用软件包回到 Buildroot 源码目录cd~/buildroot-2025.02.8makeBR2_EXTERNAL$HOME/buildroot-external-demomenuconfig本文假设此前没有使用其他外部目录。如果你已经设置了BR2_EXTERNAL应保留原有目录并把新目录追加到同一个带引号、空格分隔的路径列表中不要直接替换。在顶层找到External options进入本文的外部包菜单并勾选External options ARM64 tutorial packages [*] debug-demo上面是示意层级实际菜单可能把描述显示为提示行。也可以按/搜索BR2_PACKAGE_DEBUG_DEMO定位选项。保存并退出检查grep^BR2_PACKAGE_DEBUG_DEMO.config本次保存配置后的实际检查结果如下说明debug-demo已启用但此时还没有构建它embedembedtest:~/buildroot-2025.02.8$ grep ^BR2_PACKAGE_DEBUG_DEMO .config BR2_PACKAGE_DEBUG_DEMOyBuildroot 会把外部目录路径记录在输出目录的.br2-external.mk中本文为output/.br2-external.mk因此后续通常可以直接执行make debug-demo或make。换用新输出目录或相关记录被清理后要重新传入BR2_EXTERNAL仅备份.config并不包含这项路径记录。八、迁移说明移走旧 overlay 程序如果没有做过上一篇的 overlay 部署可以跳过本节。上一篇的rootfs-overlay/root/debug_demo对应目标端/root/debug_demo本篇则安装到/usr/bin/debug_demo。为避免误运行旧文件先把旧程序备份到 overlay 之外cd~/buildroot-2025.02.8mkdir-p~/debug-demo-backupif[-frootfs-overlay/root/debug_demo];thenmvrootfs-overlay/root/debug_demo\$HOME/debug-demo-backup/debug_demo.overlay.$(date%Y%m%d-%H%M%S)fi还要注意从 overlay 删除文件不会自动删除已经复制到output/target/的旧副本。在确认它就是前文的实验程序之后可做一次针对性的迁移清理rm-foutput/target/root/debug_demo这是一次性清理不是日常安装方式。不要删除整个output/target/原 overlay 配置和其他静态文件继续保留。已执行make clean时旧目标副本已被清理但 overlay 中的旧源文件仍需移走。如果其他已配置的 overlay 也包含usr/bin/debug_demo要先移走同名文件。overlay 在包安装之后复制到目标文件系统同一路径的旧文件可能覆盖新包产物。九、构建软件包再生成镜像1. 先单独构建这个包Ubuntu 主机执行cd~/buildroot-2025.02.8makedebug-demoV1echo$?echo $?要紧接着构建命令执行。只有返回0才继续后面的检查。V1显示实际命令便于检查源码同步、交叉编译和安装过程。检查安装结果ls-loutput/target/usr/bin/debug_demofileoutput/target/usr/bin/debug_demo重点看file输出是否包含ELF 64-bit和ARM aarch64不要把文件大小、完整 ELF 描述或时间戳当成固定值。不要直接在 Ubuntu x86_64 主机执行这个 ARM64 程序来验证运行结果。运行验证放到 QEMU 目标端。本次在 Ubuntu 主机上的文件检查结果如下不是执行 ARM64 程序的结果embedembedtest:~/buildroot-2025.02.8$ ls -l output/target/usr/bin/debug_demo -rwxr-xr-x 1 embed embed 10824 Oct 15 05:32 output/target/usr/bin/debug_demo embedembedtest:~/buildroot-2025.02.8$ file output/target/usr/bin/debug_demo output/target/usr/bin/debug_demo: ELF 64-bit LSB shared object, ARM aarch64, version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-aarch64.so.1, for GNU/Linux 6.12.0, with debug_info, not stripped其中ARM aarch64表明产物的目标架构正确with debug_info, not stripped表明此时的文件包含调试信息、尚未裁剪符号。后续生成镜像时仍可能裁剪不能据此断定镜像内的程序也保留了调试信息。2. 重新生成 rootfs 镜像make debug-demo只构建并安装软件包不会重新生成 rootfs 镜像。继续执行完整构建目标make-j2echo$?确认返回0后检查镜像ls-lhoutput/images/Image output/images/rootfs.ext2沿用前文的-j2写法不额外启用实验性的顶层并行构建选项也不要同时运行两条操作同一输出目录的构建命令。十、启动 QEMU运行镜像里的程序确认上一节完整构建成功、旧 QEMU 已退出再在 Ubuntu 主机的 Buildroot 源码目录中启动cd~/buildroot-2025.02.8 /usr/bin/qemu-system-aarch64\-Mvirt\-cpucortex-a53\-smp2\-m1G\-nographic\-kerneloutput/images/Image\-appendrootwait root/dev/vda consolettyAMA0\-drivefileoutput/images/rootfs.ext2,ifnone,formatraw,idhd0\-devicevirtio-blk-device,drivehd0\-netdevuser,idnet0,hostfwdtcp:127.0.0.1:5000-:2345\-devicevirtio-net-device,netdevnet0网络配置沿用上一篇保留本机回环地址上的 GDB 端口转发。本篇直接运行程序不依赖远程调试连接。进入目标系统并以root登录后在QEMU 目标端执行ls-l/usr/bin/debug_demo /usr/bin/debug_demoecho$?使用绝对路径是为了明确运行的是本篇软件包安装的程序而不是遗留的/root/debug_demo。这次启动后不再向目标系统传输或复制程序。本次 QEMU 目标端的实际运行记录如下# ls -l /usr/bin/debug_demo -rwxr-xr-x 1 root root 5920 Oct 15 05:34 /usr/bin/debug_demo # /usr/bin/debug_demo total 100 # echo $? 0这说明程序已经随 rootfs 镜像进入目标系统运行后输出total 100并正常退出。接下来还需通过第十一节验证修改外部源码后重建软件包和镜像能否带入新版本。十一、关键验证修改源码后不再手动复制首次输出total 100只证明程序进入了镜像。接下来用一个可见的输出变化检查“源码修改到镜像更新”的整条流程。1. 关闭 QEMU修改外部源码先在 QEMU 目标端执行poweroff。等待系统关机如果 QEMU 没有退出再按CtrlA松开后按X。确认 QEMU 已退出后再继续。在 Ubuntu 中编辑~/buildroot-external-demo/src/debug-demo/debug_demo.c找到原来的printf(total %d\n, result);只把这一行改为下面的内容然后保存文件printf(debug-demo package v2: total %d\n,result);这里的v2只是用于区分输出的测试标记不需要把包规则中的DEBUG_DEMO_VERSION 1.0改成 2.0。修改的是外部目录中的源文件不是output/build/下的副本。2. 重建软件包在 Ubuntu 主机中执行重新同步源码、编译并安装软件包cd~/buildroot-2025.02.8makedebug-demo-rebuildV1echo$?紧接着查看的返回码应为0否则先处理构建错误不继续生成镜像。在 Buildroot 2025.02.8 中本例的SITE_METHOD local使用本地源码同步机制。debug-demo-rebuild会重新同步外部源码触发编译并把新程序安装到output/target/usr/bin/debug_demo但不会更新 rootfs 镜像。仅修改本地源码后执行普通make不要期待 Buildroot 自动发现并重编译已经完成的软件包。3. 重新生成镜像继续在 Buildroot 源码目录中执行make-j2echo$?返回码为0后再启动 QEMU。这里的完整make用于把更新后的目标文件系统重新生成为镜像不是要求清理后重编译整套工具链。4. 启动新镜像核对输出使用第十节的命令重新启动 QEMU仍使用刚生成的output/images/rootfs.ext2。以root登录后在目标端执行/usr/bin/debug_demoecho$?echo $?要紧接着程序执行正常退出时应返回0。本次保存的目标端记录如下仅展示了新版输出没有记录这次的退出码# /usr/bin/debug_demo debug-demo package v2: total 100相比首次运行多出了debug-demo package v2:标记说明源码修改已进入新镜像。这次验证的关键是不手动调用交叉编译器也不手动执行cp或install部署可执行文件编译和安装由 Buildroot 的包规则完成。十二、遇到问题时检查哪里1. menuconfig 中找不到 debug-demo检查外部目录的三个入口文件是否齐全顶层Config.in的source路径是否正确以及external.desc中的ARM64_DEMO是否与路径变量一致。然后用第七节的命令显式指定BR2_EXTERNAL打开菜单。2. 提示找不到 debug_demo.c检查源码目录和文件是否存在ls-l~/buildroot-external-demo/src/debug-demo/debug_demo.cDEBUG_DEMO_SITE指向的是包含源码的目录不是 C 文件本身。还要检查拼写包目录使用debug-demo源码文件使用debug_demo.c。3. 单包构建成功QEMU 里却没有程序确认.config中存在BR2_PACKAGE_DEBUG_DEMOy单包构建后执行过完整make并且 QEMU 启动的是新生成的output/images/rootfs.ext2。4. 修改了源码运行结果仍是旧版本依次检查修改的是不是外部源码、是否执行debug-demo-rebuild、是否更新镜像并重启 QEMU、运行路径是否为/usr/bin/debug_demo以及 overlay 是否覆盖了同路径文件。如果删除过源文件、调整过构建规则或怀疑构建目录有残留可先清理本包makedebug-demo-dircleanecho$?返回0后再执行make -j2并检查返回码。它会重新构建已启用的包和镜像不删除外部源码也不会重建已有的整套工具链。十三、补充说明overlay 和软件包各管什么overlay 适合配置文件、脚本等静态内容不负责把 C 源码编译成程序需要编译的应用交给包规则避免两者管理同一目标路径。还能继续用 GDB 吗可以但 Buildroot 可能裁剪目标端程序的符号。主机 GDB 应加载本次包构建目录中未裁剪、包含调试信息的可执行文件目标端运行/usr/bin/debug_demo。两者必须来自同一次编译不能继续使用以前手动编译的旧符号文件。这条延伸调试路径尚未实测。取消勾选等于卸载吗不等于。Buildroot 不会自动清除旧安装文件dirclean也只清理本包构建目录。需要完全不含该包的干净镜像时应备份配置和自定义文件后进行完整重建。许可证怎么填写本例未指定DEBUG_DEMO_LICENSE许可证字段会显示为unknown也未提供DEBUG_DEMO_LICENSE_FILES。正式维护或分发前应按实际授权补齐不能因为使用 Buildroot 就直接把应用声明为 GPL 或 MIT。这些字段只是 Buildroot 的许可证元数据不能代替实际授权也不能证明代码权属。使用或分发第三方代码时仍须遵守其许可证要求不要把unknown理解为“没有授权限制”。本文讲解构建方法不要求博客或独立应用仅因使用 Buildroot 就采用 GPL。若另行发布源码包、工具链或系统镜像则需按其中各组件的实际许可证检查相应义务不能只看本例软件包的许可证字段。十四、小结本篇要完成的变化是之前手动编译 - 手动复制程序 - 生成镜像 现在维护源码和包规则 - Buildroot 编译并安装 - 生成镜像日常修改时记住两个动作make debug-demo-rebuild更新应用完整make更新镜像。不再手动复制程序但也不能期待普通make自动发现所有本地源码变化。这一篇把应用纳入构建流程。后续可以继续把实验配置保存为自己的 defconfig并管理 overlay 和启动脚本让整套 QEMU 实验环境更容易重新生成。参考资料Buildroot 官方手册外部目录、通用包基础设施、单包重建与文件系统定制。在线手册会随版本更新实验时也应对照 2025.02.8 源码树中的docs/manual/。Buildroot 2025.02.8 的通用包实现本地源码同步和 rebuild 目标的版本对应实现。
