十四、buildroot 系统package新增应用 编写规则

4.7.2、编写规则

1、规范概述

​ Buildroot 像一个「自动化厨房」，每个包是一道菜。如果菜名（包名）、食材位置（路径）、做法（脚本）不统一，厨房会报错。规范是让机器人（Buildroot 脚本）能读懂你的菜谱。

2、命名规则

1. 包目录名（package/ 下的文件夹）

   小写字母 + 短横线，如 package/my-app

2. 配置项名（Config.in 里的变量）

   BR2_PACKAGE_ + 包目录名大写 + 下划线分隔，如 BR2_PACKAGE_MY_APP，和包目录名严格对应（复制粘贴避免拼写错误）

3. .mk 文件中的变量

   • 包名：PKG_NAME := my-app（和目录名一致）
   • 版本：PKG_VERSION := 1.0（语义化版本）
   • 源文件：PKG_SOURCE := my_app.tar.gz（建议和包名相关）

4. 脚本中的路径

   禁止硬编码，比如 /home/user/... ，必须使用 Buildroot 内置变量：

   • $(TOPDIR)：Buildroot 根目录（自动识别）
   • $(TARGET_DIR)：最终生成的根文件系统目录（如 /output/target）
   • $(BUILD_DIR)：编译中间目录（如 /output/build）

3、文件结构

buildroot/
└─ package/
   └─ my-app/  包目录（和包名一致）
      ├─ Config.in  菜单配置（必选）
      ├─ my-app.mk  构建脚本（必选）
      └─ my_app.tar.gz   源文件（可选，本地文件）

4、Config.in 编写（让包出现在菜单里）

config BR2_PACKAGE_MY_APP  配置项名（必须和包目录名对应）
    bool "My Qt Application"  菜单显示的名称（用户看到的）
    help  帮助说明（按 H 键显示）
      这是我自己的 应用，安装到 /usr/bin/panorama
      依赖：Qt5 库

• 必须有 config 行：否则 make menuconfig 找不到你的包
• 不要用中文：菜单显示可能乱码（虽然 Buildroot 支持，但不建议）

5、.mk 文件编写（核心脚本，分 6 步）

下载源文件 → 编译 → 安装

1. 基本信息

   PKG_NAME := my-app  包名（和目录名一致）
   PKG_VERSION := 1.0  版本号
   PKG_LICENSE := MIT  许可证（必填，否则警告）
   PKG_LICENSE_FILES := LICENSE  许可证文件（如果有源文件）
   

2. 源文件位置

   • 本地文件（推荐，避免网络问题）：

     PKG_SITE := $(TOPDIR)/package/my-app  本地目录
     PKG_SOURCE := my_app.tar.gz  源文件名
     

   • 远程下载（需网络）：

     PKG_SITE := http://example.com/packages  下载地址
     PKG_SOURCE := my-app-$(PKG_VERSION).tar.gz
     

3. 解压命令

   define PKG_EXTRACT_CMDS
   	# 创建解压目录（Buildroot 自动管理，无需硬编码路径）
   	mkdir -p $(BUILD_DIR)/my-qt-app-$(PKG_VERSION)
   	# 复制本地文件到编译目录
   	cp $(PKG_SITE)/$(PKG_SOURCE) $(BUILD_DIR)/
   	# 解压（注意 .tar.gz 用 xvzf，.tar.xz 用 xvJf）
   	tar -xvzf $(BUILD_DIR)/$(PKG_SOURCE) -C $(BUILD_DIR)
   endef
   

4. 编译命令（可选）

   • 如果是预编译好的二进制文件（如果应用已经是可执行文件）：

     define PKG_BUILD_CMDS
       true  跳过编译（写 `true` 避免报错）
     endef
     

   • 如果需要编译（如 C 代码）：

     define PKG_BUILD_CMDS
       $(MAKE) -C $(BUILD_DIR)/my-app-1.0  进入源码目录编译
     endef
     

5. 安装命令

   define PKG_INSTALL_TARGET_CMDS
   	# 创建目标目录（避免因目录不存在报错）
   	mkdir -p $(TARGET_DIR)/usr/bin
   	# 安装文件（-D 自动创建路径，-m 755 设置权限）
   	install -D -m 755 $(BUILD_DIR)/my-qt-app-1.0/panorama $(TARGET_DIR)/usr/bin/panorama
   endef
   

6. 依赖项

   PKG_DEPENDS := qt5-base  依赖的包（如你的程序需要 Qt5）
   

6、package变量名规范

6.1、基础元数据后缀（必选 / 常用）

6.2、源代码处理后缀（核心）

6.3、编译与安装后缀（关键）

6.4、依赖与配置后缀

6.5、高级功能后缀（扩展）

6.6、特殊约定后缀（官方保留）