嵌入式设备上装软件最难受的不是没东西可装而是你明确知道缺一个只有几十 KB 的小工具却只能眼睁睁看着它因为固件里没这个包而跑不起来。Entware 就是为解决这类问题存在的它把一套完整的 opkg 包管理体系和软件源搬进了嵌入式设备的 /opt 目录只要设备能挂载一块可写的存储、能跑起动态链接的程序就能像在普通 Linux 上那样装包、升级、卸载。这篇内容我不打算写成手册翻译而是按我自己从零构建第一个 Entware 软件包时的顺序把包结构、工具链、打包脚本、真机部署、故障排查这几块拆开讲透。适合两类人看一是有 C 语言基础和 Linux 命令行经验、想在嵌入式环境里自己维护软件包的开发者二是手上有一台跑着精简固件的设备、想搞清楚软件包到底是怎么被组装出来的动手派。看完你应该能独立产出一个可被 opkg 正常安装、升级、卸载的 .ipk 包。1. 先搞清楚 Entware 的包管理体系长什么样动手之前我建议先花半小时把体系结构过一遍否则后面写 Makefile 的时候你会发现每个变量都像是凭空冒出来的。Entware 的核心不是某个具体程序而是三层结构叠在一起底层是 opkg 这个包管理器负责解析索引、比对版本、解包、执行安装脚本中间是软件源本质就是一份文本索引加一堆 .ipk 文件上层才是你要写的那个包定义。三层之间靠约定耦合约定错了包能打出来但装不上或者装上跑不起来。1.1 一个 .ipk 文件里到底装了些什么.ipk 的格式非常朴素它就是一个 ar 归档里面按顺序放三个成员debian-binary、control.tar.gz、data.tar.gz。debian-binary 只有一行内容 2.0纯粹是格式版本标记control.tar.gz 里放的是元信息和安装钩子脚本包括 control 文件本身以及可选的 postinst、prerm、postrm、conffilesdata.tar.gz 里放的是真正的文件树路径要写成相对于目标根目录的形式比如你要把程序装到 /opt/bin 下归档里的路径就应该是 ./opt/bin/程序名。我第一次看这个结构的时候觉得有点多余为什么不直接打个 tar.gz 加个说明文件就完了。后来理解了debian-binary 的存在让解包器可以在读任何内容之前先确认格式版本避免拿旧版解析器去读新版包control 和 data 分开则让包管理器可以在不展开完整文件树的前提下读取元信息、判断依赖、检查磁盘空间、做冲突检测。这个设计在资源紧张的嵌入式设备上特别有意义——判断一个包能不能装只需要解压几十 KB 的 control.tar.gz不用碰几 MB 的 data.tar.gz。需要注意的一个细节是 ar 成员顺序。虽然有些解析器容错但标准要求 debian-binary 必须排在第一位。我见过因为顺序错了被 opkg 直接拒绝的包错误信息还很含糊只说什么格式不支持排查了半天才发现是打包命令写成了先加 data 后加 control。所以打包命令里三个成员的出现顺序要固定下来别想着靠后处理修正。1.2 /opt 前缀与运行时的目录约定Entware 把整个运行环境收在 /opt 下这个选择不是随便定的。嵌入式固件的根文件系统通常是只读的 squashfs 或类似的只读镜像你没法往 /usr/bin 里塞东西而 /opt 往往是唯一一个挂在可写分区上的目录。把所有东西塞进 /opt就等于把系统自带的和用户装的彻底隔离开卸载的时候删干净 /opt 下的对应文件就行不会污染厂商固件。这套约定的具体布局大致是这样可执行文件在 /opt/bin 和 /opt/sbin共享库在 /opt/lib配置文件在 /opt/etc可变数据在 /opt/var临时文件在 /opt/tmp可选的共享资源在 /opt/share。opkg 自己的数据库在 /opt/lib/opkg里面记录着已安装包的文件清单、状态和脚本这个目录千万别手工改改动之后包的卸载逻辑会错乱可能出现文件残留或者误删。这里有个新手最容易忽略的点程序编译时的 prefix 必须和安装路径一致但更关键的是运行时怎么找到这些库。系统默认的库搜索路径不包含 /opt/lib所以你的程序要么用 rpath 把 /opt/lib 编译进去要么依赖环境变量 LD_LIBRARY_PATH。我个人的偏好是在编译参数里加 -Wl,-rpath,/opt/lib这样二进制自身携带了库搜索路径不依赖用户 shell 的环境配置出问题的概率小很多。代价是二进制路径写死了将来若改前缀得重新编译但 Entware 场景下前缀基本不会变这个取舍是划算的。1.3 为什么不直接把编译好的二进制拷上去很多人第一反应是我交叉编译一个二进制用文件传输工具扔到 /opt/bin 里加个执行权限不就完了干嘛折腾包格式。这个做法在一次性调试时确实快但一旦你要装第二个、第三个东西问题就成串出现了库版本冲突时你不知道谁依赖谁升级时新版本覆盖了旧版本旧版本依赖的库被一起换掉了回滚时无从下手给第二台设备部署时你得记住当初手工改了哪几个文件、权限是多少、有没有建符号链接。包管理的价值不是方便而是可追溯。每个文件属于哪个包、包与包之间的依赖关系、安装和卸载时该执行什么动作全部记录在数据库里。我在一台设备上跑了十几个自编译包之后才真正体会到这一点——某次升级一个库opkg 直接把依赖它的三个包标成了待修复一眼就能看出影响面如果全是手工拷的文件我大概要花半天时间去逐个试哪个程序崩了。还有一层现实原因是磁盘和内存。嵌入式设备存储紧张同一个库如果被多个程序依赖打成独立的库包可以让多个程序共享一份而不是每个程序都静态链接一份。静态链接虽然省事但两三个程序一叠几百 KB 就出去了在只有几十 MB 可用空间的设备上并不奢侈。2. 构建环境宿主机、工具链与目录规划环境这块我不想写成装这几个包就行的清单因为踩坑基本都踩在版本和路径上。核心原则只有一条宿主机上的一切工具只负责生成生成出来的东西必须完全不依赖宿主机。判断标准很简单用 file 命令看产物的架构用 ldd 看动态依赖只要出现宿主机特有的路径就是没配对。2.1 宿主机上到底需要装什么构建一个 .ipk 需要的工具其实很少一个能跑的编译工具链、make、tar、gzip、ar、file再加上可选的 strip 和 readelf 用于瘦身和检查。ar 和 gzip 是打包必需很多人宿主机上默认没装 binutils 里的 ar第一次打包会报命令不存在。file 用来快速确认架构我个人觉得这是最省时间的一个工具编译完第一件事就是 file 一下看一眼架构对不对比跑起来崩了再回头查要快得多。宿主机的发行版选择上我建议用你熟悉的那一套就行不用刻意追求和目标设备一致。交叉编译的意义就在于宿主机和目标机可以完全不同。但有一个坑要注意如果你用的工具链是别人打包好的它可能依赖宿主机上某个特定版本的库比如某些工具链的二进制需要较新的 glibc 才能运行。这种情况下的报错通常很隐蔽表现为工具链直接段错误或者提示找不到符号而不是给出清晰的版本提示。遇到这种先用 ldd 检查工具链自身的依赖再决定是换工具链还是补库。磁盘空间也值得提前规划。一个完整的工具链加上解压后的源码树几个 GB 是常态。我习惯在构建根目录下建三个子目录src 放下载的源码包build 放解压和编译的中间产物stage 放最终要打进包里的文件树。这三个目录分开的意义在于清理的时候可以只删 build 而不影响已下载的源码重新编译不用重复下载。源码下载在弱网环境下是很大的时间成本这个分离我建议一开始就做。2.2 交叉工具链的选择与三行验证工具链的选择取决于目标设备的 CPU 架构、字节序和 C 库。架构和字节序是硬性的C 库则是更容易被忽略的一项。如果目标设备用的是 musl你拿 glibc 工具链编出来的东西大概率跑不起来报错通常是一句很短的 not found看起来像文件不存在实际是动态链接器路径对不上。Entware 生态里常见的是 glibc 系但也有针对其他 C 库的衍生版本动手前务必确认清楚。工具链拿到手之后我建议先做三行验证再开始干活。第一行用工具链的 gcc 编一个只有 main 函数返回 0 的最小程序第二行用 file 看产物的架构描述确认和你预期的目标架构一致第三行用工具链自带的 readelf 看产物的解释器路径program interpreter这个路径必须和目标设备上的动态链接器实际路径吻合。第三行是最容易被跳过但最容易出问题的一步解释器路径不对程序在设备上就是一句 not found。关于工具链的前缀不同来源的命名习惯不一样常见形式是架构-厂商-系统-abi这种四段式比如面向 32 位 ARM 硬浮点的工具链会带 hf 后缀。这个前缀会贯穿你后面所有的编译命令和 Makefile 变量建议一开始就把它定义成一个环境变量或者 Makefile 变量别在十几处地方手打改起来太痛苦。工具链里还有一个东西经常被忘掉sysroot。交叉编译时头文件和库都应该从工具链自带的 sysroot 里取而不是从宿主机 /usr/include 里取。如果编译时报某个头文件找不到或者报结构体定义冲突八成是 include 路径混进了宿主机的。检查方法是在编译命令里加 -v 看头文件搜索顺序宿主机路径出现在 sysroot 之前就是有问题。2.3 规划一个干净的 staging 目录staging 目录也叫 DESTDIR 或安装暂存目录是整个流程里最关键的一个中间态。它的作用是承接 make install 的输出然后原封不动地被打进 data.tar.gz。这里的原则是staging 目录里的内容必须和最终设备上的文件树一一对应不多一个文件不少一个目录。我见过最常见的错误是把源码目录直接当 staging 用。make install 装完之后目录里混着编译产物、临时文件、甚至 .git 目录打出来的包体积能膨胀好几倍还会带进一些不该有的东西。解决办法是每次打包前清空 staging 目录用固定的路径重新装。清空这一步不能省因为它能保证你打出来的包是可复现的——同样的源码、同样的工具链、同样的参数产出的包内容应该完全一致。staging 目录里的路径结构要遵循前面说的 /opt 约定。也就是说如果你的程序最终要装到 /opt/bin/foo那么 staging 目录下应该是 stage/opt/bin/foo而 make install 的 prefix 参数要写成 /optDESTDIR 指向 stage。DESTDIR 和 prefix 是两个不同的东西很多人会混prefix 决定二进制里记录的路径DESTDIR 决定文件实际落在磁盘的哪里。前缀写成 /opt 而 DESTDIR 写成 stage最终文件落在 stage/opt/bin二进制里记录的路径是 /opt/bin两边都对。还有一个细节是权限。staging 目录里文件的属主和权限会原样进入 data.tar.gz在设备上解包时被保留。如果你在宿主机上是普通用户产物的属主会是你的用户名对应的 UID设备上如果没有这个 UID解包时可能报错或者落成 nobody。稳妥的做法是打包前用 tar 的 --owner0 --group0 强制归零权限则显式 chmod 控制。可执行文件 755配置文件 644需要特殊权限的单独处理别让 umask 决定最终结果。3. 从零手打第一个 .ipk我强烈建议第一个包手工打不要上来就用构建框架。框架帮你省掉的步骤恰恰是你需要理解的部分一旦出问题你会完全不知道该查哪里。手工打一个包含单个可执行文件的包整个流程不到二十行命令做完之后你对包结构的理解会比看十篇文档都扎实。3.1 control 文件每个字段都有代价control 是一个键值对格式的文本文件字段之间用空行分隔段落。必填的核心字段包括包名、版本、架构、描述可选但强烈建议填的包括依赖、分区、优先级、维护者、安装后大小。下面是我给一个演示包写的 control字段值需要按你的实际情况替换Package: hello-ent Version: 1.0.0-1 Depends: libc Source: hello-ent_1.0.0.tar.gz Section: utils Priority: optional Maintainer: dev devexample.invalid Architecture: armv7sf Installed-Size: 24 Description: Minimal demo package for build walkthrough Long description line goes here, indented by one space.包名要小写、用连字符分隔别用下划线和大写opkg 对包名的比较是严格的风格不统一会导致依赖解析时匹配不上。版本号是我建议重点想清楚的一项末尾的 -1 是包修订号源码版本没变但你改了打包方式比如加了个配置文件、调整了依赖就递增修订号而不是改前面的版本号。这样升级路径才清晰用户也能看出这次升级是换了个版本还是同一个版本重新打了包。Depends 字段的写法直接影响用户能不能装上。这里有个现实问题你写 libcopkg 在解析时会去找名为 libc 的包如果目标源里这个包的实际名字叫 libc6 或者别的依赖就永远满足不了安装直接被拒。解决方法是先在目标设备上执行列出已安装包的命令看看那些基础库的真实包名是什么照着写。别凭直觉写这一步花两分钟能省掉半小时的困惑。Architecture 字段要填目标源认可的架构标签。这类标签在嵌入式生态里通常不是简单的 arm 或 mips而是带内核 ABI 后缀的形式目的是表达这个二进制要求的最低内核版本。填错的后果是包能被安装但运行时报奇怪的错误或者 opkg 直接判定架构不匹配。稳妥做法是照抄目标设备上已有包的架构字段值用查询已安装包信息的命令就能看到。Installed-Size 单位是 KB填的是安装后占用的空间。这个值不填也能装但填了之后 opkg 在安装前的空间检查会更准确能提前拦住空间不足导致的半途失败。我一般在打包完成后用磁盘占用统计命令算一下四舍五入填进去。3.2 data.tar.gz 的文件布局与权限data.tar.gz 里放的是文件树路径必须以 ./ 开头且相对于根目录。这个 ./ 前缀不是可选的很多解析器依赖它来判断路径是相对的缺了会当成绝对路径处理安全性上直接拒绝。归档里的目录结构要和设备上的完全一致比如 ./opt/bin/hello-ent、./opt/etc/hello-ent.conf。构建这个归档时有个技巧在 staging 目录下执行打包命令用相对路径引用。命令大致是进到 stage 目录然后用 tar 打包当前目录下的 opt 子目录压缩成 gzip。注意 tar 的参数里要加 -C 指定目录别在上级目录里用绝对路径打包那样归档里会带上一长串宿主机路径。权限控制要在这里做不要指望后面的步骤。可执行文件必须是 755否则装到设备上跑不起来报的是权限拒绝而且因为文件明明存在很容易让人以为路径错了。配置文件一般 644。如果你有需要 setuid 的程序嵌入式场景少见但存在权限要显式设置因为 tar 默认会保留源文件权限。还有一点符号链接会被原样打包如果链接目标是绝对路径指向宿主机那这个链接在设备上必然是断的打包前要检查一遍。空目录的处理也值得说一句。tar 默认会打包空目录但如果你用的是某些精简版的 tar可能需要显式指定参数。空目录在什么场景下重要比如你的程序运行时需要一个 /opt/var/run 目录来放 pid 文件如果安装后这个目录不存在程序启动就会失败。这种情况有两种处理方式一是在 data.tar.gz 里带上空目录二是在 postinst 脚本里创建。我个人倾向于在脚本里创建因为目录的权限和属主在脚本里可以精确控制而且卸载时可以对应删除不留在文件系统里变成孤儿。3.3 ar 封装与产物自检三个组件准备好之后封装命令很简单就是在工作目录下依次把 debian-binary、control.tar.gz、data.tar.gz 加进 ar 归档顺序不能乱输出文件名必须以 .ipk 结尾。这里有个容易踩的坑ar 命令的某些实现默认会往归档里加符号表或者文件名索引这在标准 ar 归档里是不期望的。如果打包后发现 opkg 报格式错误先检查归档里是不是多了成员用列出归档成员的命令看一眼就知道。自检我一般做三步缺一不可。第一步列出归档成员确认恰好三个且顺序正确。第二步展开 control.tar.gz确认 control 文件内容完整、没有多余文件、换行符是 Unix 格式。第三步展开 data.tar.gz 并列出文件逐条核对路径、权限、有无多余文件。第三步最花时间但最值得我有一次就是因为漏了这一步把一个 .swp 临时文件打进了包装到设备上虽然不影响运行但卸载时它被当作包的一部分删掉了反过来如果它在包外就会残留。还有一步可选但推荐检查 data.tar.gz 的压缩率。如果压缩后体积和未压缩差不多说明你打进去的东西可能已经是压缩格式比如一堆 .gz 文件这时候可以用不压缩的方式打外层避免二次压缩浪费时间。不过大多数场景下这个优化意义不大包体积本来就不大压缩开销可以忽略。4. 用 Makefile 把流程固化下来手工打一次包是为了理解第二次开始就该固化了。固化的目的不是省几条命令而是保证可复现——三个月后你回头看能通过 make 一条命令产出和当初一模一样的包不依赖你当时的记忆力。4.1 目录结构与变量约定我习惯的目录结构是这样的顶层放 Makefile下面 src 放源码压缩包build 放解压和编译的中间产物stage 作为安装暂存dist 放最终产出的 .ipk。这个结构的好处是每个目录职责单一清理规则也容易写。变量方面把工具链前缀、目标架构、包名、版本号、安装前缀全部提到 Makefile 顶部后面所有规则引用变量改架构或者改版本只改一处。变量定义里有两组容易混的CROSS 指的是工具链前缀比如四段式的架构前缀PREFIX 指的是安装路径前缀Entware 场景下是 /opt。这两者名字像但含义完全不同我建议在 Makefile 里加注释写清楚否则过几个月自己都会看错。还有一组是 CC 和 STRIP前者用交叉编译器后者用工具链自带的 strip千万别用宿主机的 strip架构不匹配时会直接报错或者产出损坏的二进制。4.2 编译、安装、打包三个 target 怎么写我把流程拆成三个主 targetfetch、build、package。fetch 负责下载和解压源码判断依据是 build 目录下的解压标记文件存在就跳过。build 依赖 fetch负责配置和编译配置时把 prefix 设为 /opt把 host 设为工具链前缀。package 依赖 build负责清空 stage、执行安装、瘦身、打 control 和 data 两个归档、封装成 .ipk。下面是一个简化后的 Makefile 骨架实际使用时把变量值替换成你自己的PKG_NAME : hello-ent PKG_VER : 1.0.0 PKG_REL : 1 ARCH : armv7sf CROSS : arm-linux-gnueabihf- PREFIX : /opt SRC_TAR : $(PKG_NAME)_$(PKG_VER).tar.gz BUILD_DIR : build/$(PKG_NAME)-$(PKG_VER) STAGE_DIR : stage DIST_DIR : dist .PHONY: all fetch build package clean all: package fetch: test -f $(BUILD_DIR)/.fetched || \ ( mkdir -p build tar xzf src/$(SRC_TAR) -C build touch $(BUILD_DIR)/.fetched ) build: fetch cd $(BUILD_DIR) ./configure --host$(CROSS) --prefix$(PREFIX) $(MAKE) -C $(BUILD_DIR) package: build rm -rf $(STAGE_DIR) $(MAKE) -C $(BUILD_DIR) install DESTDIR$(CURDIR)/$(STAGE_DIR) find $(STAGE_DIR) -type f -exec $(CROSS)strip --strip-unneeded {} \; 2/dev/null || true mkdir -p $(DIST_DIR) ./scripts/mkipk.sh $(STAGE_DIR) $(DIST_DIR)/$(PKG_NAME)_$(PKG_VER)-$(PKG_REL)_$(ARCH).ipk打包的具体逻辑我放在一个独立脚本里因为 shell 里要处理临时目录、生成 control、打两个归档写成 Makefile 规则会很难读。脚本的大致逻辑是建一个临时目录写入 debian-binary生成 control 文件把 stage 目录打成 data.tar.gz把 control 文件打成 control.tar.gz最后用 ar 封装清理临时目录。把这段逻辑抽出来还有一个好处多包的工程可以复用同一个脚本只传不同的参数。4.3 增量构建与清理增量构建的关键是把下载源码和解压源码分开判断。下载用压缩包的修改时间或者校验和判断解压用标记文件判断。我在 fetch 里用标记文件是因为它最直观解压成功后立刻 touch 一个 .fetched下次 make 看到文件存在就跳过整段。这样即使源码目录被手工改过只要标记文件在也不会重复解压覆盖你的改动——当然这也意味着改了源码要手动删标记这个取舍我认为是合理的毕竟改源码是少数情况。clean 规则要分两级。一级是轻清理只删 stage 和 dist保留 build二级是彻底清理连 build 一起删。日常调试基本用一级因为重新下载解压源码的时间成本很高。彻底清理只在换工具链或者换源码版本时用。这个分离我在好几个项目里都用效果很好尤其是网络不好的时候能省下大量等待。还有一个细节是 make 的并行。如果你的包编译量大可以在编译规则里加 -j 参数但要注意 configure 阶段不能并行必须串行完成之后才能并行编译。Makefile 的依赖关系本身保证了这一点只要写对 target 依赖make -j 是安全的。但如果你的 Makefile 里有手工写的 cd 命令和顺序敏感的操作并行就可能出问题这种情况老老实实串行。5. 真机部署安装、升级、卸载的完整闭环包打出来了接下来是装到设备上。这一步看着简单实际是问题最集中的地方因为涉及到设备端的环境、已有包版本、磁盘空间、权限很多问题只有到了这一步才暴露出来。5.1 装之前先做兼容性预检预检清单我一般看四项。第一项是架构和内核把目标设备上某个已装包的架构标签拉出来和你包的 Architecture 字段比对同时确认设备内核版本不低于标签里暗示的版本要求。第二项是 C 库确认工具链用的 C 库和目标设备一致glibc 和 musl 的二进制不能混用这个错误在运行时的表现极具误导性报的是文件不存在。第三项是磁盘空间用设备上的空间统计命令看 /opt 所在分区剩余对比 control 里填的 Installed-Size留出至少两倍余量。第四项是依赖把 Depends 里的每个包名在设备上实际查一遍确认名字对得上、版本满足。第三项经常被低估。嵌入式设备的可写分区往往只有几十 MB而且被日志、临时文件占着。安装过程中解包是先把文件解到临时位置再移动需要的空间可能比最终占用还多。空间不够的表现是安装中途失败然后留下一个半装状态既不能用也不能干净卸载处理起来很麻烦。所以我习惯装之前先清一遍临时目录把余量留足。第四项里的依赖检查有个实用技巧先在设备上查询你依赖的那个包是否已安装及版本和你 control 里写的依赖约束做比对。如果你的依赖写的是某个包 某版本而设备上是更低的版本opkg 会尝试升级那个包这时要确认软件源里有可用的新版本否则安装会失败。稳妥的做法是第一次发布时依赖写宽松一点等确认生态稳定了再收紧。5.2 从安装到卸载的完整体验安装本地包用的命令是带着路径的 installopkg 会先读取包的 control检查依赖和冲突然后解包 data最后执行 postinst。整个过程的输出信息值得逐行看完尤其是关于包已降级或者依赖被自动处理的提示这些往往预示着后续的问题。装完之后立刻做三件事验证。第一查询这个包的状态确认状态字段是已安装而不是半配置。第二检查文件是否在预期路径用打包时记录的清单核对一遍特别是可执行文件的权限。第三直接运行程序跑一个最简单的功能比如打印版本号。这三步能在几十秒内发现问题比等到真正使用时才发现要好得多。升级的流程要注意一点opkg 升级时会先执行旧版本的 prerm再解包新版本最后执行新版本的 postinst。如果你的 prerm 脚本里做了不可逆的操作比如删配置文件升级之后配置就丢了。正确做法是配置文件的清理放在 postrm 里并且只在真正卸载而不是升级时执行。判断的方法是看脚本的第一个参数卸载和升级传的值不一样脚本里做分支处理。卸载的时候opkg 会先执行 prerm再逐个删除 data 清单里的文件最后执行 postrm。这里有个细节如果某个文件在安装后被用户修改过并且你在 control 里配了 conffiles 声明它是配置文件opkg 默认会保留它并提示用户。没有声明的文件会被直接删除。所以任何用户可能修改的文件都应该在 conffiles 里列出来否则用户改的配置在卸载或者升级时就无声无息地没了。5.3 安装脚本钩子的正确用法postinst 是在文件解包之后执行的这时候文件已经在位可以做初始化。我常用它来做三件事创建运行时需要的目录、生成默认配置如果不存在、重新加载受影响的配置。第三件事在嵌入式设备上要谨慎因为很多服务并没有完善的重载机制强行重启可能导致短暂的服务中断。我的做法是在 postinst 里只打印提示让用户自己决定什么时候重启相关服务。脚本的第一行要写解释器路径。这里有个坑设备上 bash 不一定存在很多精简系统只有 /bin/sh而 /bin/sh 可能是 busybox 提供的语法支持有限。我所有的安装脚本都用最保守的 shell 语法写不用数组、不用 [[ ]]、不用花括号扩展测试时也尽量在真实的设备环境里跑一遍别只在宿主机的 bash 上验证就结束。脚本必须以正确的退出码结束。postinst 返回非零opkg 会把包标记为安装失败但文件已经解包了就变成了半装状态。如果脚本里有非关键步骤失败了用逻辑或加 true 兜住别让整条命令链断掉。反过来如果失败会影响程序正确运行比如目录没创建成功那就应该让它返回非零让问题尽早暴露而不是装上一个跑不起来的包。还有一个实践细节脚本里的错误输出要写清楚。嵌入式设备上排查问题的手段有限用户能看到的往往就是安装过程的输出。一句创建目录失败和一句mkdir: cannot create directory /opt/var/x: No space left on device排查效率差很多。我习惯在关键步骤前加提示在失败时带上具体的路径和错误原因。6. 常见故障与排查实录这一节是踩坑记录按发生阶段分类。每个阶段的问题特征不一样排查手段也不一样分开看能少走弯路。6.1 编译期架构对、符号缺、路径错编译期的第一个高频问题是头文件找不到。如果报的是标准库头文件找不到八成是工具链的 sysroot 没配好编译器去宿主机 /usr/include 里找找到了也不一定能用。排查方法是编译单个文件时加详细输出看头文件搜索顺序宿主机路径排在前面就是有问题。如果是项目自己的头文件找不到检查 configure 的 --host 参数有没有传对有些构建系统会根据 host 参数推导包含路径。第二个高频问题是链接时找不到库。交叉编译场景下链接器默认只从工具链 sysroot 里找库宿主机 /usr/lib 里的库是看不见的。如果你的项目依赖一个用 pkg-config 报告的库而 pkg-config 返回的是宿主机的路径链接就会失败。解决办法是设置环境变量把 pkg-config 的搜索路径指向 sysroot或者直接在 configure 参数里用 LDFLAGS 显式指定库路径。第三个问题是编译出来的东西架构不对。这种错误通常在产物阶段才被发现运行时报格式错误。成因可能是 make 用了缓存里宿主机编译的中间文件obj 文件没清也可能是某个子模块自己调用了不带前缀的 gcc。前者清理 build 目录重来后者要检查项目里有没有写死的 gcc 调用改成用 CC 变量。还有个不那么常见但很难查的问题交叉编译器版本太高生成的二进制用了新的 libc 特性目标设备上的 libc 版本太低不支持。表现是程序启动时报某个符号找不到。这类问题没法靠改编译参数解决只能换用和目标设备 libc 版本匹配的工具链或者把新库一起打包进去。6.2 安装期依赖、冲突、空间安装期的第一个问题是依赖不满足。opkg 的报错会明确列出哪些依赖没满足但有时候列出的名字看着陌生那是因为依赖链上有传递依赖你只写了 AA 又依赖 BB 不在源里。排查方法是在设备上先试着装 A 本身看能不能装上装不上说明源里缺需要你先把 B 也打包发布。第二个问题是包冲突。多个包提供了同一个文件后装的会覆盖先装的卸载时又会删掉别的包需要的文件。这类问题在共享库上最常见。避免方法是在打包时严格检查 data 清单里的路径确保每个路径只属于一个包公共库单独打成库包其他包用 Depends 引用。第三个问题是空间不足。前面说过这个问题的表现是安装中途失败留下半装状态。清理办法是先卸载这个包的残留如果卸载也失败就手工删掉 data 清单里的残留文件再清一次 opkg 的状态记录。这一步要谨慎手工改数据库有风险最好先备份数据库目录。第四个问题相对隐蔽包能装上但文件的权限不对程序跑不起来。这通常是打包时 staging 目录的权限没控制好。检查方法是列出安装后的文件权限和预期比对。修复方法是修正 staging 里的权限后重新打包而不是在设备上手工 chmod因为手工改的权限在下次升级时会丢。6.3 运行期加载、路径、环境运行期最常见的问题是文件不存在但文件明明在。这个报错绝大多数情况下是动态链接器路径不对或者依赖的共享库找不到。排查顺序是先用 readelf 看二进制的解释器路径确认这个路径在设备上存在再用工具看二进制的库依赖列表逐个确认这些库在设备上的位置最后检查这些库的路径是否在运行时的库搜索路径里。第二个问题是能找到库但版本不对。表现是启动时报某个符号找不到或者行为异常。这类问题在升级了某个库但没升级依赖它的程序时出现。解决办法是把依赖关系写进 Depends 的版本约束里让 opkg 在升级库的时候一并升级受影响的包。第三个问题是环境变量相关的。很多程序依赖 PATH、HOME、TERM 这些变量在交互式 shell 里跑没问题放到服务或者计划任务里跑就失败。这类问题的排查方法是把运行环境的变量全部打印出来对比。我个人的经验是所有需要长期运行的程序都应该在启动脚本里显式设置必需的环境变量不要依赖登录 shell 的配置。第四个问题是配置文件位置。程序默认可能在 /etc 下找配置但 Entware 的约定是 /opt/etc。这类问题需要在编译时用参数指定配置路径或者写启动脚本时用命令行参数指定。两者选一个我倾向于编译时定好因为这样程序在任何调用方式下行为一致不依赖启动脚本。6.4 一张常见故障对照表现象高概率原因快速验证方法处理方向安装时提示格式不支持ar 成员顺序错或有多余成员列出归档成员看顺序重新按顺序封装安装时依赖无法满足依赖包名与源中实际名不符在设备上查询该包实际名称修正 Depends 字段安装中途失败并留残留磁盘空间不足查看分区剩余空间清理后重装装上了但无法执行文件权限不是 755查看文件权限位修正 staging 权限重打包执行时提示文件不存在动态链接器路径或库路径不对查看解释器路径与库依赖修正 rpath 或补库启动时报符号未定义依赖库版本过低查看已安装库版本加版本约束或同步升级卸载后文件仍残留运行时生成的文件未清理查看安装清单外的文件在 postrm 里清升级后配置文件丢失未声明为配置文件查看 control 的 conffiles补声明后重发版这张表我建议打印出来贴在工位上大部分问题都能在前两列对上号。剩下的少数问题需要具体分析但排查方向基本跑不出这个范围。7. 进阶多子包、依赖与长期维护单个包跑通之后真实需求往往更复杂一个源码树要拆成运行包和开发包多个包共享同一个库版本需要长期维护。这一节讲的就是这些工程化的部分。7.1 一个源码拆成多个子包拆包的基本原则是按使用场景分而不是按文件类型分。典型拆法是运行包和开发包分开运行包只放可执行文件和运行必需的库开发包放头文件、静态库、pkg-config 文件开发包 Depends 运行包。这样普通用户装运行包不会带进几十 MB 的开发文件而在设备上做二次开发的人装开发包就能编译。拆包在构建时的做法是从同一份 staging 里按路径前缀挑文件打成不同的 data.tar.gz各自配一份 control。这里要注意依赖方向运行包不能依赖开发包反过来可以。还有文件归属要清晰一个文件只能出现在一个包里否则升级时两个包都认为自己拥有它行为不可预测。还有一个拆包维度是可选功能。比如一个程序可以编译进对某些库的支持这些库如果不常用把带和不带的版本拆成两个包会增大维护成本。我的做法是默认都编进去如果某个依赖确实太重比如占了包体积的一半以上再考虑拆。拆之前先算一下拆开之后用户要装两个包才能用完整功能这个体验损失值不值得省下的那点空间。7.2 依赖声明与实际运行库的对应Depends 字段写什么取决于你的二进制实际链接了什么。推导方法是看二进制的动态依赖列表把每个库映射到提供它的包名。这里最容易出错的是隐式依赖某些库在链接时被间接引入你没有直接调用它的函数但二进制里确实有对它的依赖。这类依赖漏写用户装上之后运行就崩。我的做法是在打包脚本里加一步自动检查用工具导出二进制的依赖库列表和 control 里声明的依赖做对比发现没覆盖的库就打警告。这个检查不需要很精确只要能提示出有个库没在依赖里就够了人工再判断要不要加。这一步在我自己的流程里拦住过好几次漏依赖的问题。版本约束的写法要看实际需要。如果只是需要某个库存在写包名就行如果某个功能依赖库的新版本就写大于等于某版本。写法上要克制约束太严会导致用户环境里明明有可用的库却装不上约束太松又可能导致运行期问题。我的经验是只在确实遇到版本兼容问题时才加约束而不是预防性地加一堆。7.3 版本号策略与软件源索引维护版本号策略我遵循三个规则。源码升级改主版本号打包方式变化改修订号包名不变。这样用户升级时会看到版本号变化能判断这次升级的影响。不要在同一个版本号下偷偷改包内容一旦出现同样的版本号行为不一样的情况排查成本极高。软件源索引需要随之更新。索引本质是一个文本文件列出每个包的元信息和文件校验和。包发布之后索引必须重新生成否则设备上的包管理器看不到新版本。索引里的校验和字段一定要算对算错了设备下载完会校验失败报的是比较晦涩的错误。索引维护里有个细节容易被忽略旧版本的包文件不要立刻删。有些用户的依赖链固定在旧版本上你删了旧包他们的安装会失败。稳妥做法是保留最近两三个版本等确认没有用户依赖了再清理。这个策略在存储空间紧张的环境里要权衡但包文件本身不大保留几个版本的成本通常可以接受。最后说一个长期维护的习惯每次发布包除了包文件本身同时留一份构建记录写清楚用的工具链版本、源码版本、关键编译参数。这看起来是多此一举但当你半年后需要复现某个版本的行为或者排查为什么这个版本和那个版本行为不同时这份记录能省下大量时间。我现在的做法是把这些信息直接写进包的 description 字段的扩展行里随包一起走不依赖额外的文档。我个人在做的过程中最大的体会是打包这件事的难点从来不在命令本身而在那些没写在文档里的约定——路径前缀要一致、权限要显式、依赖要和实际链接对上、脚本要用最保守的语法。这些东西每一条单独看都很小但漏掉任何一条包就会以某种莫名其妙的方式失败而且报错信息和真实原因往往对不上。所以我在新环境里第一次打包时宁可多花半小时把这些约定一条条验证一遍也不愿意事后花两小时去猜一个文件不存在到底是什么意思。
嵌入式设备上装软件最难受的不是没东西可装而是你明确知道缺一个只有几十 KB 的小工具却只能眼睁睁看着它因为固件里没这个包而跑不起来。Entware 就是为解决这类问题存在的它把一套完整的 opkg 包管理体系和软件源搬进了嵌入式设备的 /opt 目录只要设备能挂载一块可写的存储、能跑起动态链接的程序就能像在普通 Linux 上那样装包、升级、卸载。这篇内容我不打算写成手册翻译而是按我自己从零构建第一个 Entware 软件包时的顺序把包结构、工具链、打包脚本、真机部署、故障排查这几块拆开讲透。适合两类人看一是有 C 语言基础和 Linux 命令行经验、想在嵌入式环境里自己维护软件包的开发者二是手上有一台跑着精简固件的设备、想搞清楚软件包到底是怎么被组装出来的动手派。看完你应该能独立产出一个可被 opkg 正常安装、升级、卸载的 .ipk 包。1. 先搞清楚 Entware 的包管理体系长什么样动手之前我建议先花半小时把体系结构过一遍否则后面写 Makefile 的时候你会发现每个变量都像是凭空冒出来的。Entware 的核心不是某个具体程序而是三层结构叠在一起底层是 opkg 这个包管理器负责解析索引、比对版本、解包、执行安装脚本中间是软件源本质就是一份文本索引加一堆 .ipk 文件上层才是你要写的那个包定义。三层之间靠约定耦合约定错了包能打出来但装不上或者装上跑不起来。1.1 一个 .ipk 文件里到底装了些什么.ipk 的格式非常朴素它就是一个 ar 归档里面按顺序放三个成员debian-binary、control.tar.gz、data.tar.gz。debian-binary 只有一行内容 2.0纯粹是格式版本标记control.tar.gz 里放的是元信息和安装钩子脚本包括 control 文件本身以及可选的 postinst、prerm、postrm、conffilesdata.tar.gz 里放的是真正的文件树路径要写成相对于目标根目录的形式比如你要把程序装到 /opt/bin 下归档里的路径就应该是 ./opt/bin/程序名。我第一次看这个结构的时候觉得有点多余为什么不直接打个 tar.gz 加个说明文件就完了。后来理解了debian-binary 的存在让解包器可以在读任何内容之前先确认格式版本避免拿旧版解析器去读新版包control 和 data 分开则让包管理器可以在不展开完整文件树的前提下读取元信息、判断依赖、检查磁盘空间、做冲突检测。这个设计在资源紧张的嵌入式设备上特别有意义——判断一个包能不能装只需要解压几十 KB 的 control.tar.gz不用碰几 MB 的 data.tar.gz。需要注意的一个细节是 ar 成员顺序。虽然有些解析器容错但标准要求 debian-binary 必须排在第一位。我见过因为顺序错了被 opkg 直接拒绝的包错误信息还很含糊只说什么格式不支持排查了半天才发现是打包命令写成了先加 data 后加 control。所以打包命令里三个成员的出现顺序要固定下来别想着靠后处理修正。1.2 /opt 前缀与运行时的目录约定Entware 把整个运行环境收在 /opt 下这个选择不是随便定的。嵌入式固件的根文件系统通常是只读的 squashfs 或类似的只读镜像你没法往 /usr/bin 里塞东西而 /opt 往往是唯一一个挂在可写分区上的目录。把所有东西塞进 /opt就等于把系统自带的和用户装的彻底隔离开卸载的时候删干净 /opt 下的对应文件就行不会污染厂商固件。这套约定的具体布局大致是这样可执行文件在 /opt/bin 和 /opt/sbin共享库在 /opt/lib配置文件在 /opt/etc可变数据在 /opt/var临时文件在 /opt/tmp可选的共享资源在 /opt/share。opkg 自己的数据库在 /opt/lib/opkg里面记录着已安装包的文件清单、状态和脚本这个目录千万别手工改改动之后包的卸载逻辑会错乱可能出现文件残留或者误删。这里有个新手最容易忽略的点程序编译时的 prefix 必须和安装路径一致但更关键的是运行时怎么找到这些库。系统默认的库搜索路径不包含 /opt/lib所以你的程序要么用 rpath 把 /opt/lib 编译进去要么依赖环境变量 LD_LIBRARY_PATH。我个人的偏好是在编译参数里加 -Wl,-rpath,/opt/lib这样二进制自身携带了库搜索路径不依赖用户 shell 的环境配置出问题的概率小很多。代价是二进制路径写死了将来若改前缀得重新编译但 Entware 场景下前缀基本不会变这个取舍是划算的。1.3 为什么不直接把编译好的二进制拷上去很多人第一反应是我交叉编译一个二进制用文件传输工具扔到 /opt/bin 里加个执行权限不就完了干嘛折腾包格式。这个做法在一次性调试时确实快但一旦你要装第二个、第三个东西问题就成串出现了库版本冲突时你不知道谁依赖谁升级时新版本覆盖了旧版本旧版本依赖的库被一起换掉了回滚时无从下手给第二台设备部署时你得记住当初手工改了哪几个文件、权限是多少、有没有建符号链接。包管理的价值不是方便而是可追溯。每个文件属于哪个包、包与包之间的依赖关系、安装和卸载时该执行什么动作全部记录在数据库里。我在一台设备上跑了十几个自编译包之后才真正体会到这一点——某次升级一个库opkg 直接把依赖它的三个包标成了待修复一眼就能看出影响面如果全是手工拷的文件我大概要花半天时间去逐个试哪个程序崩了。还有一层现实原因是磁盘和内存。嵌入式设备存储紧张同一个库如果被多个程序依赖打成独立的库包可以让多个程序共享一份而不是每个程序都静态链接一份。静态链接虽然省事但两三个程序一叠几百 KB 就出去了在只有几十 MB 可用空间的设备上并不奢侈。2. 构建环境宿主机、工具链与目录规划环境这块我不想写成装这几个包就行的清单因为踩坑基本都踩在版本和路径上。核心原则只有一条宿主机上的一切工具只负责生成生成出来的东西必须完全不依赖宿主机。判断标准很简单用 file 命令看产物的架构用 ldd 看动态依赖只要出现宿主机特有的路径就是没配对。2.1 宿主机上到底需要装什么构建一个 .ipk 需要的工具其实很少一个能跑的编译工具链、make、tar、gzip、ar、file再加上可选的 strip 和 readelf 用于瘦身和检查。ar 和 gzip 是打包必需很多人宿主机上默认没装 binutils 里的 ar第一次打包会报命令不存在。file 用来快速确认架构我个人觉得这是最省时间的一个工具编译完第一件事就是 file 一下看一眼架构对不对比跑起来崩了再回头查要快得多。宿主机的发行版选择上我建议用你熟悉的那一套就行不用刻意追求和目标设备一致。交叉编译的意义就在于宿主机和目标机可以完全不同。但有一个坑要注意如果你用的工具链是别人打包好的它可能依赖宿主机上某个特定版本的库比如某些工具链的二进制需要较新的 glibc 才能运行。这种情况下的报错通常很隐蔽表现为工具链直接段错误或者提示找不到符号而不是给出清晰的版本提示。遇到这种先用 ldd 检查工具链自身的依赖再决定是换工具链还是补库。磁盘空间也值得提前规划。一个完整的工具链加上解压后的源码树几个 GB 是常态。我习惯在构建根目录下建三个子目录src 放下载的源码包build 放解压和编译的中间产物stage 放最终要打进包里的文件树。这三个目录分开的意义在于清理的时候可以只删 build 而不影响已下载的源码重新编译不用重复下载。源码下载在弱网环境下是很大的时间成本这个分离我建议一开始就做。2.2 交叉工具链的选择与三行验证工具链的选择取决于目标设备的 CPU 架构、字节序和 C 库。架构和字节序是硬性的C 库则是更容易被忽略的一项。如果目标设备用的是 musl你拿 glibc 工具链编出来的东西大概率跑不起来报错通常是一句很短的 not found看起来像文件不存在实际是动态链接器路径对不上。Entware 生态里常见的是 glibc 系但也有针对其他 C 库的衍生版本动手前务必确认清楚。工具链拿到手之后我建议先做三行验证再开始干活。第一行用工具链的 gcc 编一个只有 main 函数返回 0 的最小程序第二行用 file 看产物的架构描述确认和你预期的目标架构一致第三行用工具链自带的 readelf 看产物的解释器路径program interpreter这个路径必须和目标设备上的动态链接器实际路径吻合。第三行是最容易被跳过但最容易出问题的一步解释器路径不对程序在设备上就是一句 not found。关于工具链的前缀不同来源的命名习惯不一样常见形式是架构-厂商-系统-abi这种四段式比如面向 32 位 ARM 硬浮点的工具链会带 hf 后缀。这个前缀会贯穿你后面所有的编译命令和 Makefile 变量建议一开始就把它定义成一个环境变量或者 Makefile 变量别在十几处地方手打改起来太痛苦。工具链里还有一个东西经常被忘掉sysroot。交叉编译时头文件和库都应该从工具链自带的 sysroot 里取而不是从宿主机 /usr/include 里取。如果编译时报某个头文件找不到或者报结构体定义冲突八成是 include 路径混进了宿主机的。检查方法是在编译命令里加 -v 看头文件搜索顺序宿主机路径出现在 sysroot 之前就是有问题。2.3 规划一个干净的 staging 目录staging 目录也叫 DESTDIR 或安装暂存目录是整个流程里最关键的一个中间态。它的作用是承接 make install 的输出然后原封不动地被打进 data.tar.gz。这里的原则是staging 目录里的内容必须和最终设备上的文件树一一对应不多一个文件不少一个目录。我见过最常见的错误是把源码目录直接当 staging 用。make install 装完之后目录里混着编译产物、临时文件、甚至 .git 目录打出来的包体积能膨胀好几倍还会带进一些不该有的东西。解决办法是每次打包前清空 staging 目录用固定的路径重新装。清空这一步不能省因为它能保证你打出来的包是可复现的——同样的源码、同样的工具链、同样的参数产出的包内容应该完全一致。staging 目录里的路径结构要遵循前面说的 /opt 约定。也就是说如果你的程序最终要装到 /opt/bin/foo那么 staging 目录下应该是 stage/opt/bin/foo而 make install 的 prefix 参数要写成 /optDESTDIR 指向 stage。DESTDIR 和 prefix 是两个不同的东西很多人会混prefix 决定二进制里记录的路径DESTDIR 决定文件实际落在磁盘的哪里。前缀写成 /opt 而 DESTDIR 写成 stage最终文件落在 stage/opt/bin二进制里记录的路径是 /opt/bin两边都对。还有一个细节是权限。staging 目录里文件的属主和权限会原样进入 data.tar.gz在设备上解包时被保留。如果你在宿主机上是普通用户产物的属主会是你的用户名对应的 UID设备上如果没有这个 UID解包时可能报错或者落成 nobody。稳妥的做法是打包前用 tar 的 --owner0 --group0 强制归零权限则显式 chmod 控制。可执行文件 755配置文件 644需要特殊权限的单独处理别让 umask 决定最终结果。3. 从零手打第一个 .ipk我强烈建议第一个包手工打不要上来就用构建框架。框架帮你省掉的步骤恰恰是你需要理解的部分一旦出问题你会完全不知道该查哪里。手工打一个包含单个可执行文件的包整个流程不到二十行命令做完之后你对包结构的理解会比看十篇文档都扎实。3.1 control 文件每个字段都有代价control 是一个键值对格式的文本文件字段之间用空行分隔段落。必填的核心字段包括包名、版本、架构、描述可选但强烈建议填的包括依赖、分区、优先级、维护者、安装后大小。下面是我给一个演示包写的 control字段值需要按你的实际情况替换Package: hello-ent Version: 1.0.0-1 Depends: libc Source: hello-ent_1.0.0.tar.gz Section: utils Priority: optional Maintainer: dev devexample.invalid Architecture: armv7sf Installed-Size: 24 Description: Minimal demo package for build walkthrough Long description line goes here, indented by one space.包名要小写、用连字符分隔别用下划线和大写opkg 对包名的比较是严格的风格不统一会导致依赖解析时匹配不上。版本号是我建议重点想清楚的一项末尾的 -1 是包修订号源码版本没变但你改了打包方式比如加了个配置文件、调整了依赖就递增修订号而不是改前面的版本号。这样升级路径才清晰用户也能看出这次升级是换了个版本还是同一个版本重新打了包。Depends 字段的写法直接影响用户能不能装上。这里有个现实问题你写 libcopkg 在解析时会去找名为 libc 的包如果目标源里这个包的实际名字叫 libc6 或者别的依赖就永远满足不了安装直接被拒。解决方法是先在目标设备上执行列出已安装包的命令看看那些基础库的真实包名是什么照着写。别凭直觉写这一步花两分钟能省掉半小时的困惑。Architecture 字段要填目标源认可的架构标签。这类标签在嵌入式生态里通常不是简单的 arm 或 mips而是带内核 ABI 后缀的形式目的是表达这个二进制要求的最低内核版本。填错的后果是包能被安装但运行时报奇怪的错误或者 opkg 直接判定架构不匹配。稳妥做法是照抄目标设备上已有包的架构字段值用查询已安装包信息的命令就能看到。Installed-Size 单位是 KB填的是安装后占用的空间。这个值不填也能装但填了之后 opkg 在安装前的空间检查会更准确能提前拦住空间不足导致的半途失败。我一般在打包完成后用磁盘占用统计命令算一下四舍五入填进去。3.2 data.tar.gz 的文件布局与权限data.tar.gz 里放的是文件树路径必须以 ./ 开头且相对于根目录。这个 ./ 前缀不是可选的很多解析器依赖它来判断路径是相对的缺了会当成绝对路径处理安全性上直接拒绝。归档里的目录结构要和设备上的完全一致比如 ./opt/bin/hello-ent、./opt/etc/hello-ent.conf。构建这个归档时有个技巧在 staging 目录下执行打包命令用相对路径引用。命令大致是进到 stage 目录然后用 tar 打包当前目录下的 opt 子目录压缩成 gzip。注意 tar 的参数里要加 -C 指定目录别在上级目录里用绝对路径打包那样归档里会带上一长串宿主机路径。权限控制要在这里做不要指望后面的步骤。可执行文件必须是 755否则装到设备上跑不起来报的是权限拒绝而且因为文件明明存在很容易让人以为路径错了。配置文件一般 644。如果你有需要 setuid 的程序嵌入式场景少见但存在权限要显式设置因为 tar 默认会保留源文件权限。还有一点符号链接会被原样打包如果链接目标是绝对路径指向宿主机那这个链接在设备上必然是断的打包前要检查一遍。空目录的处理也值得说一句。tar 默认会打包空目录但如果你用的是某些精简版的 tar可能需要显式指定参数。空目录在什么场景下重要比如你的程序运行时需要一个 /opt/var/run 目录来放 pid 文件如果安装后这个目录不存在程序启动就会失败。这种情况有两种处理方式一是在 data.tar.gz 里带上空目录二是在 postinst 脚本里创建。我个人倾向于在脚本里创建因为目录的权限和属主在脚本里可以精确控制而且卸载时可以对应删除不留在文件系统里变成孤儿。3.3 ar 封装与产物自检三个组件准备好之后封装命令很简单就是在工作目录下依次把 debian-binary、control.tar.gz、data.tar.gz 加进 ar 归档顺序不能乱输出文件名必须以 .ipk 结尾。这里有个容易踩的坑ar 命令的某些实现默认会往归档里加符号表或者文件名索引这在标准 ar 归档里是不期望的。如果打包后发现 opkg 报格式错误先检查归档里是不是多了成员用列出归档成员的命令看一眼就知道。自检我一般做三步缺一不可。第一步列出归档成员确认恰好三个且顺序正确。第二步展开 control.tar.gz确认 control 文件内容完整、没有多余文件、换行符是 Unix 格式。第三步展开 data.tar.gz 并列出文件逐条核对路径、权限、有无多余文件。第三步最花时间但最值得我有一次就是因为漏了这一步把一个 .swp 临时文件打进了包装到设备上虽然不影响运行但卸载时它被当作包的一部分删掉了反过来如果它在包外就会残留。还有一步可选但推荐检查 data.tar.gz 的压缩率。如果压缩后体积和未压缩差不多说明你打进去的东西可能已经是压缩格式比如一堆 .gz 文件这时候可以用不压缩的方式打外层避免二次压缩浪费时间。不过大多数场景下这个优化意义不大包体积本来就不大压缩开销可以忽略。4. 用 Makefile 把流程固化下来手工打一次包是为了理解第二次开始就该固化了。固化的目的不是省几条命令而是保证可复现——三个月后你回头看能通过 make 一条命令产出和当初一模一样的包不依赖你当时的记忆力。4.1 目录结构与变量约定我习惯的目录结构是这样的顶层放 Makefile下面 src 放源码压缩包build 放解压和编译的中间产物stage 作为安装暂存dist 放最终产出的 .ipk。这个结构的好处是每个目录职责单一清理规则也容易写。变量方面把工具链前缀、目标架构、包名、版本号、安装前缀全部提到 Makefile 顶部后面所有规则引用变量改架构或者改版本只改一处。变量定义里有两组容易混的CROSS 指的是工具链前缀比如四段式的架构前缀PREFIX 指的是安装路径前缀Entware 场景下是 /opt。这两者名字像但含义完全不同我建议在 Makefile 里加注释写清楚否则过几个月自己都会看错。还有一组是 CC 和 STRIP前者用交叉编译器后者用工具链自带的 strip千万别用宿主机的 strip架构不匹配时会直接报错或者产出损坏的二进制。4.2 编译、安装、打包三个 target 怎么写我把流程拆成三个主 targetfetch、build、package。fetch 负责下载和解压源码判断依据是 build 目录下的解压标记文件存在就跳过。build 依赖 fetch负责配置和编译配置时把 prefix 设为 /opt把 host 设为工具链前缀。package 依赖 build负责清空 stage、执行安装、瘦身、打 control 和 data 两个归档、封装成 .ipk。下面是一个简化后的 Makefile 骨架实际使用时把变量值替换成你自己的PKG_NAME : hello-ent PKG_VER : 1.0.0 PKG_REL : 1 ARCH : armv7sf CROSS : arm-linux-gnueabihf- PREFIX : /opt SRC_TAR : $(PKG_NAME)_$(PKG_VER).tar.gz BUILD_DIR : build/$(PKG_NAME)-$(PKG_VER) STAGE_DIR : stage DIST_DIR : dist .PHONY: all fetch build package clean all: package fetch: test -f $(BUILD_DIR)/.fetched || \ ( mkdir -p build tar xzf src/$(SRC_TAR) -C build touch $(BUILD_DIR)/.fetched ) build: fetch cd $(BUILD_DIR) ./configure --host$(CROSS) --prefix$(PREFIX) $(MAKE) -C $(BUILD_DIR) package: build rm -rf $(STAGE_DIR) $(MAKE) -C $(BUILD_DIR) install DESTDIR$(CURDIR)/$(STAGE_DIR) find $(STAGE_DIR) -type f -exec $(CROSS)strip --strip-unneeded {} \; 2/dev/null || true mkdir -p $(DIST_DIR) ./scripts/mkipk.sh $(STAGE_DIR) $(DIST_DIR)/$(PKG_NAME)_$(PKG_VER)-$(PKG_REL)_$(ARCH).ipk打包的具体逻辑我放在一个独立脚本里因为 shell 里要处理临时目录、生成 control、打两个归档写成 Makefile 规则会很难读。脚本的大致逻辑是建一个临时目录写入 debian-binary生成 control 文件把 stage 目录打成 data.tar.gz把 control 文件打成 control.tar.gz最后用 ar 封装清理临时目录。把这段逻辑抽出来还有一个好处多包的工程可以复用同一个脚本只传不同的参数。4.3 增量构建与清理增量构建的关键是把下载源码和解压源码分开判断。下载用压缩包的修改时间或者校验和判断解压用标记文件判断。我在 fetch 里用标记文件是因为它最直观解压成功后立刻 touch 一个 .fetched下次 make 看到文件存在就跳过整段。这样即使源码目录被手工改过只要标记文件在也不会重复解压覆盖你的改动——当然这也意味着改了源码要手动删标记这个取舍我认为是合理的毕竟改源码是少数情况。clean 规则要分两级。一级是轻清理只删 stage 和 dist保留 build二级是彻底清理连 build 一起删。日常调试基本用一级因为重新下载解压源码的时间成本很高。彻底清理只在换工具链或者换源码版本时用。这个分离我在好几个项目里都用效果很好尤其是网络不好的时候能省下大量等待。还有一个细节是 make 的并行。如果你的包编译量大可以在编译规则里加 -j 参数但要注意 configure 阶段不能并行必须串行完成之后才能并行编译。Makefile 的依赖关系本身保证了这一点只要写对 target 依赖make -j 是安全的。但如果你的 Makefile 里有手工写的 cd 命令和顺序敏感的操作并行就可能出问题这种情况老老实实串行。5. 真机部署安装、升级、卸载的完整闭环包打出来了接下来是装到设备上。这一步看着简单实际是问题最集中的地方因为涉及到设备端的环境、已有包版本、磁盘空间、权限很多问题只有到了这一步才暴露出来。5.1 装之前先做兼容性预检预检清单我一般看四项。第一项是架构和内核把目标设备上某个已装包的架构标签拉出来和你包的 Architecture 字段比对同时确认设备内核版本不低于标签里暗示的版本要求。第二项是 C 库确认工具链用的 C 库和目标设备一致glibc 和 musl 的二进制不能混用这个错误在运行时的表现极具误导性报的是文件不存在。第三项是磁盘空间用设备上的空间统计命令看 /opt 所在分区剩余对比 control 里填的 Installed-Size留出至少两倍余量。第四项是依赖把 Depends 里的每个包名在设备上实际查一遍确认名字对得上、版本满足。第三项经常被低估。嵌入式设备的可写分区往往只有几十 MB而且被日志、临时文件占着。安装过程中解包是先把文件解到临时位置再移动需要的空间可能比最终占用还多。空间不够的表现是安装中途失败然后留下一个半装状态既不能用也不能干净卸载处理起来很麻烦。所以我习惯装之前先清一遍临时目录把余量留足。第四项里的依赖检查有个实用技巧先在设备上查询你依赖的那个包是否已安装及版本和你 control 里写的依赖约束做比对。如果你的依赖写的是某个包 某版本而设备上是更低的版本opkg 会尝试升级那个包这时要确认软件源里有可用的新版本否则安装会失败。稳妥的做法是第一次发布时依赖写宽松一点等确认生态稳定了再收紧。5.2 从安装到卸载的完整体验安装本地包用的命令是带着路径的 installopkg 会先读取包的 control检查依赖和冲突然后解包 data最后执行 postinst。整个过程的输出信息值得逐行看完尤其是关于包已降级或者依赖被自动处理的提示这些往往预示着后续的问题。装完之后立刻做三件事验证。第一查询这个包的状态确认状态字段是已安装而不是半配置。第二检查文件是否在预期路径用打包时记录的清单核对一遍特别是可执行文件的权限。第三直接运行程序跑一个最简单的功能比如打印版本号。这三步能在几十秒内发现问题比等到真正使用时才发现要好得多。升级的流程要注意一点opkg 升级时会先执行旧版本的 prerm再解包新版本最后执行新版本的 postinst。如果你的 prerm 脚本里做了不可逆的操作比如删配置文件升级之后配置就丢了。正确做法是配置文件的清理放在 postrm 里并且只在真正卸载而不是升级时执行。判断的方法是看脚本的第一个参数卸载和升级传的值不一样脚本里做分支处理。卸载的时候opkg 会先执行 prerm再逐个删除 data 清单里的文件最后执行 postrm。这里有个细节如果某个文件在安装后被用户修改过并且你在 control 里配了 conffiles 声明它是配置文件opkg 默认会保留它并提示用户。没有声明的文件会被直接删除。所以任何用户可能修改的文件都应该在 conffiles 里列出来否则用户改的配置在卸载或者升级时就无声无息地没了。5.3 安装脚本钩子的正确用法postinst 是在文件解包之后执行的这时候文件已经在位可以做初始化。我常用它来做三件事创建运行时需要的目录、生成默认配置如果不存在、重新加载受影响的配置。第三件事在嵌入式设备上要谨慎因为很多服务并没有完善的重载机制强行重启可能导致短暂的服务中断。我的做法是在 postinst 里只打印提示让用户自己决定什么时候重启相关服务。脚本的第一行要写解释器路径。这里有个坑设备上 bash 不一定存在很多精简系统只有 /bin/sh而 /bin/sh 可能是 busybox 提供的语法支持有限。我所有的安装脚本都用最保守的 shell 语法写不用数组、不用 [[ ]]、不用花括号扩展测试时也尽量在真实的设备环境里跑一遍别只在宿主机的 bash 上验证就结束。脚本必须以正确的退出码结束。postinst 返回非零opkg 会把包标记为安装失败但文件已经解包了就变成了半装状态。如果脚本里有非关键步骤失败了用逻辑或加 true 兜住别让整条命令链断掉。反过来如果失败会影响程序正确运行比如目录没创建成功那就应该让它返回非零让问题尽早暴露而不是装上一个跑不起来的包。还有一个实践细节脚本里的错误输出要写清楚。嵌入式设备上排查问题的手段有限用户能看到的往往就是安装过程的输出。一句创建目录失败和一句mkdir: cannot create directory /opt/var/x: No space left on device排查效率差很多。我习惯在关键步骤前加提示在失败时带上具体的路径和错误原因。6. 常见故障与排查实录这一节是踩坑记录按发生阶段分类。每个阶段的问题特征不一样排查手段也不一样分开看能少走弯路。6.1 编译期架构对、符号缺、路径错编译期的第一个高频问题是头文件找不到。如果报的是标准库头文件找不到八成是工具链的 sysroot 没配好编译器去宿主机 /usr/include 里找找到了也不一定能用。排查方法是编译单个文件时加详细输出看头文件搜索顺序宿主机路径排在前面就是有问题。如果是项目自己的头文件找不到检查 configure 的 --host 参数有没有传对有些构建系统会根据 host 参数推导包含路径。第二个高频问题是链接时找不到库。交叉编译场景下链接器默认只从工具链 sysroot 里找库宿主机 /usr/lib 里的库是看不见的。如果你的项目依赖一个用 pkg-config 报告的库而 pkg-config 返回的是宿主机的路径链接就会失败。解决办法是设置环境变量把 pkg-config 的搜索路径指向 sysroot或者直接在 configure 参数里用 LDFLAGS 显式指定库路径。第三个问题是编译出来的东西架构不对。这种错误通常在产物阶段才被发现运行时报格式错误。成因可能是 make 用了缓存里宿主机编译的中间文件obj 文件没清也可能是某个子模块自己调用了不带前缀的 gcc。前者清理 build 目录重来后者要检查项目里有没有写死的 gcc 调用改成用 CC 变量。还有个不那么常见但很难查的问题交叉编译器版本太高生成的二进制用了新的 libc 特性目标设备上的 libc 版本太低不支持。表现是程序启动时报某个符号找不到。这类问题没法靠改编译参数解决只能换用和目标设备 libc 版本匹配的工具链或者把新库一起打包进去。6.2 安装期依赖、冲突、空间安装期的第一个问题是依赖不满足。opkg 的报错会明确列出哪些依赖没满足但有时候列出的名字看着陌生那是因为依赖链上有传递依赖你只写了 AA 又依赖 BB 不在源里。排查方法是在设备上先试着装 A 本身看能不能装上装不上说明源里缺需要你先把 B 也打包发布。第二个问题是包冲突。多个包提供了同一个文件后装的会覆盖先装的卸载时又会删掉别的包需要的文件。这类问题在共享库上最常见。避免方法是在打包时严格检查 data 清单里的路径确保每个路径只属于一个包公共库单独打成库包其他包用 Depends 引用。第三个问题是空间不足。前面说过这个问题的表现是安装中途失败留下半装状态。清理办法是先卸载这个包的残留如果卸载也失败就手工删掉 data 清单里的残留文件再清一次 opkg 的状态记录。这一步要谨慎手工改数据库有风险最好先备份数据库目录。第四个问题相对隐蔽包能装上但文件的权限不对程序跑不起来。这通常是打包时 staging 目录的权限没控制好。检查方法是列出安装后的文件权限和预期比对。修复方法是修正 staging 里的权限后重新打包而不是在设备上手工 chmod因为手工改的权限在下次升级时会丢。6.3 运行期加载、路径、环境运行期最常见的问题是文件不存在但文件明明在。这个报错绝大多数情况下是动态链接器路径不对或者依赖的共享库找不到。排查顺序是先用 readelf 看二进制的解释器路径确认这个路径在设备上存在再用工具看二进制的库依赖列表逐个确认这些库在设备上的位置最后检查这些库的路径是否在运行时的库搜索路径里。第二个问题是能找到库但版本不对。表现是启动时报某个符号找不到或者行为异常。这类问题在升级了某个库但没升级依赖它的程序时出现。解决办法是把依赖关系写进 Depends 的版本约束里让 opkg 在升级库的时候一并升级受影响的包。第三个问题是环境变量相关的。很多程序依赖 PATH、HOME、TERM 这些变量在交互式 shell 里跑没问题放到服务或者计划任务里跑就失败。这类问题的排查方法是把运行环境的变量全部打印出来对比。我个人的经验是所有需要长期运行的程序都应该在启动脚本里显式设置必需的环境变量不要依赖登录 shell 的配置。第四个问题是配置文件位置。程序默认可能在 /etc 下找配置但 Entware 的约定是 /opt/etc。这类问题需要在编译时用参数指定配置路径或者写启动脚本时用命令行参数指定。两者选一个我倾向于编译时定好因为这样程序在任何调用方式下行为一致不依赖启动脚本。6.4 一张常见故障对照表现象高概率原因快速验证方法处理方向安装时提示格式不支持ar 成员顺序错或有多余成员列出归档成员看顺序重新按顺序封装安装时依赖无法满足依赖包名与源中实际名不符在设备上查询该包实际名称修正 Depends 字段安装中途失败并留残留磁盘空间不足查看分区剩余空间清理后重装装上了但无法执行文件权限不是 755查看文件权限位修正 staging 权限重打包执行时提示文件不存在动态链接器路径或库路径不对查看解释器路径与库依赖修正 rpath 或补库启动时报符号未定义依赖库版本过低查看已安装库版本加版本约束或同步升级卸载后文件仍残留运行时生成的文件未清理查看安装清单外的文件在 postrm 里清升级后配置文件丢失未声明为配置文件查看 control 的 conffiles补声明后重发版这张表我建议打印出来贴在工位上大部分问题都能在前两列对上号。剩下的少数问题需要具体分析但排查方向基本跑不出这个范围。7. 进阶多子包、依赖与长期维护单个包跑通之后真实需求往往更复杂一个源码树要拆成运行包和开发包多个包共享同一个库版本需要长期维护。这一节讲的就是这些工程化的部分。7.1 一个源码拆成多个子包拆包的基本原则是按使用场景分而不是按文件类型分。典型拆法是运行包和开发包分开运行包只放可执行文件和运行必需的库开发包放头文件、静态库、pkg-config 文件开发包 Depends 运行包。这样普通用户装运行包不会带进几十 MB 的开发文件而在设备上做二次开发的人装开发包就能编译。拆包在构建时的做法是从同一份 staging 里按路径前缀挑文件打成不同的 data.tar.gz各自配一份 control。这里要注意依赖方向运行包不能依赖开发包反过来可以。还有文件归属要清晰一个文件只能出现在一个包里否则升级时两个包都认为自己拥有它行为不可预测。还有一个拆包维度是可选功能。比如一个程序可以编译进对某些库的支持这些库如果不常用把带和不带的版本拆成两个包会增大维护成本。我的做法是默认都编进去如果某个依赖确实太重比如占了包体积的一半以上再考虑拆。拆之前先算一下拆开之后用户要装两个包才能用完整功能这个体验损失值不值得省下的那点空间。7.2 依赖声明与实际运行库的对应Depends 字段写什么取决于你的二进制实际链接了什么。推导方法是看二进制的动态依赖列表把每个库映射到提供它的包名。这里最容易出错的是隐式依赖某些库在链接时被间接引入你没有直接调用它的函数但二进制里确实有对它的依赖。这类依赖漏写用户装上之后运行就崩。我的做法是在打包脚本里加一步自动检查用工具导出二进制的依赖库列表和 control 里声明的依赖做对比发现没覆盖的库就打警告。这个检查不需要很精确只要能提示出有个库没在依赖里就够了人工再判断要不要加。这一步在我自己的流程里拦住过好几次漏依赖的问题。版本约束的写法要看实际需要。如果只是需要某个库存在写包名就行如果某个功能依赖库的新版本就写大于等于某版本。写法上要克制约束太严会导致用户环境里明明有可用的库却装不上约束太松又可能导致运行期问题。我的经验是只在确实遇到版本兼容问题时才加约束而不是预防性地加一堆。7.3 版本号策略与软件源索引维护版本号策略我遵循三个规则。源码升级改主版本号打包方式变化改修订号包名不变。这样用户升级时会看到版本号变化能判断这次升级的影响。不要在同一个版本号下偷偷改包内容一旦出现同样的版本号行为不一样的情况排查成本极高。软件源索引需要随之更新。索引本质是一个文本文件列出每个包的元信息和文件校验和。包发布之后索引必须重新生成否则设备上的包管理器看不到新版本。索引里的校验和字段一定要算对算错了设备下载完会校验失败报的是比较晦涩的错误。索引维护里有个细节容易被忽略旧版本的包文件不要立刻删。有些用户的依赖链固定在旧版本上你删了旧包他们的安装会失败。稳妥做法是保留最近两三个版本等确认没有用户依赖了再清理。这个策略在存储空间紧张的环境里要权衡但包文件本身不大保留几个版本的成本通常可以接受。最后说一个长期维护的习惯每次发布包除了包文件本身同时留一份构建记录写清楚用的工具链版本、源码版本、关键编译参数。这看起来是多此一举但当你半年后需要复现某个版本的行为或者排查为什么这个版本和那个版本行为不同时这份记录能省下大量时间。我现在的做法是把这些信息直接写进包的 description 字段的扩展行里随包一起走不依赖额外的文档。我个人在做的过程中最大的体会是打包这件事的难点从来不在命令本身而在那些没写在文档里的约定——路径前缀要一致、权限要显式、依赖要和实际链接对上、脚本要用最保守的语法。这些东西每一条单独看都很小但漏掉任何一条包就会以某种莫名其妙的方式失败而且报错信息和真实原因往往对不上。所以我在新环境里第一次打包时宁可多花半小时把这些约定一条条验证一遍也不愿意事后花两小时去猜一个文件不存在到底是什么意思。
