OpenWrt编译时提示“Package xxx not found”，如何添加自定义软件包？

Question

**问题：** 在OpenWrt编译过程中，执行 `make menuconfig` 后勾选了某软件包（如 `curl`、`mosquitto` 或自定义工具），但运行 `make` 时却报错：“`Package xxx not found`”。该提示并非因拼写错误或未启用对应选项，而是因为该软件包未存在于当前OpenWrt源码树的 `package/` 目录中——可能属于官方仓库已移除的旧包、第三方维护包，或完全自研的私有模块。此时，标准 `feeds update && feeds install` 也无法解决。开发者需手动集成：包括准备符合OpenWrt Buildroot规范的Makefile、patch、配置文件（Kconfig）、依赖声明及交叉编译适配。常见疏漏包括：Makefile命名不规范（如未以`Makefile`全大写命名）、未正确设置`PKG_NAME`/`PKG_VERSION`、遗漏`$(Package/xxx)`宏定义，或未在`package/`子目录下正确注册。如何系统性地添加并验证一个自定义软件包，使其被编译系统识别并成功构建？

Answer 1

```html

一、现象定位：从报错日志反向追溯编译系统行为

当执行 make 时出现 Package xxx not found，OpenWrt Buildroot 并非简单“找不到文件”，而是未通过三重注册校验：① package/ 目录下存在合法子目录；② 子目录内含规范命名的 Makefile（全大写、无扩展名）；③ 该 Makefile 被顶层 package/Makefile 递归包含。可运行 make V=s | grep -A5 "xxx" 查看解析阶段是否跳过该包。

二、结构合规性：自定义包的标准目录树与命名契约

• 必须路径：package/myapp/Makefile（大小写敏感，不可为 makefile 或 Makefile.in）
• 可选但推荐：package/myapp/src/（源码）、package/myapp/patches/（.patch 文件）、package/myapp/Config.in（Kconfig 条目）
• 禁止嵌套：不得将包置于 package/utils/ 或 package/network/ 等已有分类子目录下——Buildroot 不自动扫描二级路径

三、Makefile 核心骨架：七要素缺一不可

include $(TOPDIR)/rules.mk

PKG_NAME:=curl
PKG_VERSION:=8.9.1
PKG_RELEASE:=1
PKG_SOURCE:=curl-$(PKG_VERSION).tar.gz
PKG_SOURCE_URL:=https://curl.se/download/
PKG_HASH:=a1b2c3...  # 必须提供 SHA256
PKG_BUILD_DIR:=$(BUILD_DIR)/curl-$(PKG_VERSION)

include $(INCLUDE_DIR)/package.mk

define Package/curl
  SECTION:=net
  CATEGORY:=Network
  TITLE:=Command line tool and library for transferring data with URLs
  DEPENDS:=+libopenssl +zlib
endef

define Package/curl/description
  curl is a command line tool for transferring data with URL syntax.
endef

define Build/Prepare
	$(call Build/Prepare/Default)
endef

define Build/Configure
	$(call Build/Configure/Default, \
		--enable-http \
		--enable-https \
		--without-libidn2 \
		--with-ssl="$(STAGING_DIR)/usr" \
	)
endef

define Build/Compile
	$(call Build/Compile/Default)
endef

define Package/curl/install
	$(INSTALL_DIR) $(1)/usr/bin
	$(INSTALL_BIN) $(PKG_BUILD_DIR)/src/curl $(1)/usr/bin/
endef

$(eval $(call BuildPackage,curl))

四、Kconfig 集成：让 make menuconfig 可见可选

在 package/myapp/Config.in 中声明：

config PACKAGE_myapp
	tristate "myapp - Custom utility"
	default n
	depends on !DISABLE_IPV6  # 可选依赖约束
	help
		This is a custom OpenWrt package built from source.
		Select this to include it in firmware image.

并确保其被主 Kconfig 包含：检查 package/Config.in 是否有 source "package/myapp/Config.in" —— 若无，需手动追加。

五、依赖与交叉编译适配：关键陷阱排查清单

风险点	典型表现	修复方式
PKG_INSTALL:=1 缺失	configure 成功但 install 步骤跳过	添加 PKG_INSTALL:=1 并定义 Package/xxx/install
未设置 STAGING_DIR 路径	链接 libssl 失败：cannot find -lssl	在 Build/Configure 中显式传入 --with-ssl="$(STAGING_DIR)/usr"

六、验证闭环：四阶渐进式调试法

1. 静态检查：运行 make package/myapp/{clean,compile} V=s 2>&1 | head -20 观察是否进入 prepare 阶段
2. 菜单可见性：执行 make menuconfig → 进入 Network → 确认 myapp 出现在列表且可勾选（M 或 *）
3. 依赖图谱：运行 make package/myapp/depinfo 输出所有隐式依赖（含工具链、库、host-builds）
4. 固件注入：启用后执行 make -j1 V=s |& grep -E "(myapp|curl|mosquitto)" 确认 build log 含 Installing package myapp

七、高级场景：第三方包迁移与版本降级策略

若需集成已从 packages feed 移除的老版 mosquitto（如 v1.4.x），应：

• 从 openwrt/packages@openwrt-22.03 找到对应 commit，用 git archive 导出子目录
• 将 mosquitto/Makefile 中的 PKG_SOURCE_VERSION 改为具体 tag，并更新 PKG_HASH（用 make package/mosquitto/download PKG_HASH= 自动生成）
• 禁用 feeds 冲突：在 feeds.conf.default 中注释掉 src-git packages https://... 行，避免 feeds install -a 覆盖手动包

八、自动化加固：CI/CD 中的包健康度检查脚本

#!/bin/sh
# validate-package.sh
PKG="myapp"
test -d "package/$PKG" || { echo "FAIL: dir missing"; exit 1; }
test -f "package/$PKG/Makefile" || { echo "FAIL: Makefile missing"; exit 1; }
grep -q "PKG_NAME:=$PKG" "package/$PKG/Makefile" || { echo "FAIL: PKG_NAME mismatch"; exit 1; }
grep -q "BuildPackage" "package/$PKG/Makefile" || { echo "FAIL: BuildPackage macro missing"; exit 1; }
echo "PASS: $PKG structure validated"

九、错误模式映射表：精准定位疏漏根源

graph TD A[make menuconfig 勾选] --> B{make 报 Package xxx not found} B --> C1[package/xxx/ 不存在] B --> C2[package/xxx/Makefile 名称错误] B --> C3[Makefile 中缺少 define Package/xxx] B --> C4[Config.in 未被主 Kconfig 包含] B --> C5[PKG_NAME 与 menuconfig 中 symbol 名不一致] C1 --> D[创建目录并复制骨架] C2 --> D C3 --> E[补全 Package/xxx 宏及 BuildPackage 调用] C4 --> F[编辑 package/Config.in 追加 source] C5 --> G[统一为小写无下划线，如 PKG_NAME:=curl → PACKAGE_curl]

十、生产就绪：签名、审计与灰度发布建议

在企业级 OpenWrt 定制中，自定义包需满足：

• 来源可信：所有 PKG_SOURCE_URL 必须指向 HTTPS + 已知 GPG 公钥托管站（如 curl.se、mosquitto.org）
• 构建可重现：使用 PKG_HASH 而非 PKG_MD5SUM，并在 CI 中启用 CONFIG_CCACHE=y 与 CONFIG_PACKAGE_myapp=y 固定配置
• 灰度验证：先构建为 IPK（make package/myapp/compile），scp 至目标设备执行 opkg install /tmp/myapp_*.ipk，再决定是否纳入固件镜像

```