Make 参考

以下命令在主仓库根目录执行。首次构建参见从源码构建。

常用命令

make help                 # 默认目标；仅显示帮助
make doctor               # 检查环境
make fetch                # 获取固定版本依赖
make build                # 构建组件
make image                # 打包、验证并发布匹配镜像集
make check                # 主机、文档和设备树检查
make flash-existing-all   # 烧录已有匹配集，不构建

所有构建采用完整开发板配置和原生 -Os 体积优化。 Linux 使用上游 TRIM_UNUSED_KSYMS 并保留自动生成的无线导入白名单；ext4 内置。 主机路径和并行任务数可写入忽略跟踪的 local.mk，例如 JOBS := 4。DEBUG=1 增加诊断配置。

构建目标

目标

说明

help

显示公共命令；这是默认目标

doctor

检查主机、工具链和 ESP-IDF 环境

fetch

初始化子模块，获取工具链、BTstack 和 rootfs 源码缓存

fetch-rootfs

获取所选 Buildroot 软件包源码，不构建目标软件包

download

单独初始化源码子模块，不与构建目标混用

toolchain-fetch

下载并验证固定版本 Linux 工具链

toolchain

检查已安装工具链，不进行下载

toolchain-source

使用指定 crosstool-NG 源码构建工具链

build

构建启动固件、Linux、rootfs 和无线镜像

image、all、flash-image

构建、生成合并镜像和清单，验证后发布至 dist/

opensbi

为 FIT 构建并验证 fw_dynamic.bin

uboot、bootloader

构建 SPL、spl_app.bin 和 u-boot.itb

linux

构建 XIP 内核、DTB、DTBO 和无线模块

rootfs、initramfs

构建 SquashFS 根文件系统 out/images/rootfs.sqfs

idf-check

根据依赖锁检查 ESP-IDF

radio-idf-deps

构建 ESP-IDF 无线依赖

radio-linux-payload

生成无线中间载荷、导入桩及内核导出白名单

radio-module

检查集成无线模块和载荷输出

radio-image、radio-fs

创建预链接 out/images/radio.bin

radio-package

从已验证输出打包 out/images/esp32s31-radio-engineering-only.tar.xz，不构建

lp-firmware

构建 out/lp/ 并暂存到 out/staging/overlay/

persist

创建空的 out/images/persist.jffs2，不烧录

coremark

构建基准测试，并复制到 out/staging/coremark/coremark.exe

buildroot-menuconfig

打开 Buildroot 配置菜单

buildroot-clean、buildroot-reconfigure

删除 Buildroot 输出以便按新输入重建

clean

删除构建树、生成文件、暂存、镜像及报告；保留缓存

fullclean

执行 clean；同样保留下载和工具链缓存

check-layout

检查共享 Flash 和内存布局

check-host

检查布局并运行主机回归测试，不获取依赖

check-docs

使用严格 Sphinx 警告设置构建文档

check-dt

使用项目交叉编译器验证设备树和绑定

check、check-fast

运行主机、文档和设备树检查

check-artifacts

验证 out/images/build-manifest.json 及匹配产物

build-manifest

生成 out/images/build-manifest.json

最终产物位于 out/images/；验证后发布的镜像集位于 dist/，由 dist/current 选择当前集合。 原生组件对象、生成文件、暂存和报告位于 out/，下载与工具链缓存位于 cache/。

Linux、U-Boot 和无线配置输入变化会触发原生重新配置；输入未变时保留增量构建。 Buildroot 软件包选择或工具链变化则需要先运行 make buildroot-reconfigure， 删除选定的 Buildroot 输出树后再构建。执行前应把菜单中的预期更改保存到受版本控制的 defconfig；需要长期保留的内核选项应写回 defconfig 或 configs/kernel/。

ROOTFS_BASELINE=/absolute/path/to/rootfs.sqfs 显式选择增量重新打包，并记录来源。 它检查必需的完整用户空间运行文件及精确模块列表，不完整的基础镜像会被拒绝； 这不是干净的 Buildroot 重建，也不代表继承的用户空间二进制已经按 -Os 重新编译。 只有缺少标准日志/cron 启动脚本时，才可通过 ROOTFS_BUSYBOX_BUILD=/path/to/busybox-build 显式允许从固定版本的 Buildroot 源码恢复它们。 重新打包工具核对继承二进制中的 applet/帮助字节，记录新增脚本，并保留现有文件系统元数据。

烧录目标

默认串口为 /dev/ttyUSB0，波特率 2000000：

make PORT=/dev/ttyUSB1 BAUD=921600 flash-existing-all

目标

行为

flash-existing-all、flash-all

验证并烧录 dist/current 中的六个匹配组件，不重新构建

build-flash

先执行 image，再烧录已验证匹配集

flash-bootloader、flash-opensbi、flash-linux、flash-dtb

拒绝部分更新，因为无法确认已安装的配套组件

flash-radio、flash-existing-radio、flash-rootfs、flash-existing-rootfs

同样拒绝部分更新

flash-persist、erase

拒绝执行；破坏性维护需要独立、明确的流程

烧录工具只解析一次 dist/current，随后验证并使用该不可变镜像集。清单核对组件和 合并镜像哈希、无线的内核/模块/载荷/导入绑定及配置身份；这些主机检查不能证明硬件启动成功。

同布局的匹配组件更新保留 persist；合并镜像烧录会覆盖 persist。改变布局前应备份并全新安装。环境安装、连接与控制台步骤见烧录与首次启动。

构建变量

变量

用途

PORT、BAUD

烧录连接

JOBS

并行编译数，默认主机 CPU 数量

DEBUG

1 启用额外诊断配置

OUT_ROOT

构建输出根目录，默认 out/

CACHE_DIR

共享缓存根目录，默认 cache/

DEFCONFIG

原生内核 defconfig，默认 esp32s31_defconfig

LINUX_TARGET

内核镜像目标，默认 xipImage

IDF_EXPORT

ESP-IDF export.sh 路径

IDF_PATH、IDF_ROOT

ESP-IDF 安装及查找路径

HOST_PYTHON

U-Boot 主机解释器，包含 env-shebang 工具；默认取当前 python3，激活 ESP-IDF 时应显式选择已准备依赖的主机解释器

UBOOT_PYTHONPATH

该 U-Boot 主机解释器可选的额外模块搜索路径

TOOLCHAIN_PREFIX

已安装 Linux 工具链目录

TOOLCHAIN_RELEASE_TAG

configs/build-versions.mk 选择的版本

CROSSTOOL_NG_DIR

toolchain-source 使用的源码目录

S31_ALLOW_UNPINNED

显式启用实验性的非固定 ESP-IDF 版本

ROOTFS_BASELINE

显式请求从已有 rootfs 增量重新打包，保留来源记录

ROOTFS_BUSYBOX_BUILD

用于验证缺失标准服务脚本能否恢复的现有 BusyBox 构建目录

集成构建始终包含 Wi-Fi/蓝牙组合载荷；运行模式由板端 esp32-config 选择。OpenSBI 的 FW_TEXT_START 为 0x4000E400，FW_RW_START 为 0x2F00F000。Linux CONFIG_XIP_PHYS_ADDR 为 0x40400000，是 CPU 物理地址；对应原始 Flash 偏移 0x400000。更改布局必须同步验证链接、映射及设备树，见Flash 布局。