Make reference
Run GNU Make from the parent repository. Component-native systems own compilation; the parent selects configuration inputs, output paths, ordering, validation and publication. For installation, see Build from source.
Common commands
make help # Default; no build or hardware access
make doctor # Diagnose host tools and configured paths
make fetch # Explicitly prepare pinned dependencies
make build # Build the matched component set
make image # Merge, verify and publish the image set
make check # Host, documentation and devicetree checks
Every build uses the full board configuration and native -Os optimization.
Linux uses upstream TRIM_UNUSED_KSYMS with the generated radio import
whitelist; ext4 is built in. DEBUG=1 adds the debug fragment.
Use JOBS=4 to bound native parallelism. Machine paths and job limits may be set
in ignored local.mk. See Build configuration.
Build targets
Target |
Description |
|---|---|
|
Show the public commands; this is the default target |
|
Diagnose host tools and configured paths |
|
Build boot firmware, Linux, rootfs and the paired radio image |
|
Build, merge, verify and atomically publish the image set |
|
Explicitly prepare pinned sources, toolchain, BTstack and Buildroot downloads |
|
Fetch the selected Buildroot package sources without building target packages |
|
Initialize pinned source submodules |
|
Validate an installed toolchain |
|
Fetch the pinned prebuilt Linux toolchain |
|
Build a toolchain from configured crosstool-NG source |
|
Build native OpenSBI output |
|
Build SPL, ROM wrapper and FIT |
|
Build XIP kernel, device trees, overlays and radio module |
|
Build the SquashFS root filesystem |
|
Build the ESP-IDF radio dependency closure |
|
Build the intermediate payload, import stubs, and kernel export whitelist |
|
Build and check the radio module and payload outputs |
|
Build the radio XIP image bound to this kernel/module |
|
Package verified existing outputs as |
|
Build LP firmware and stage it in the build staging overlay |
|
Create an empty JFFS2 image; does not flash it |
|
Build and copy the benchmark into build staging |
|
Open Buildroot configuration |
|
Remove only the selected Buildroot output |
|
Check ESP-IDF against the dependency lock |
|
Validate flash, SRAM, linker and devicetree contracts |
|
Run host regression tests without downloads or hardware |
|
Build documentation with strict Sphinx warnings |
|
Validate device trees, schemas and overlays |
|
Combine host, documentation and devicetree validation |
|
Verify existing artifacts and record build provenance |
|
Verify existing images against |
|
Remove the build output; retain shared caches |
Final build artifacts live in out/images/; verified published sets live in
dist/, with dist/current selecting the current set. Native component
objects, generated files, staging and reports stay under out/. Downloads
and toolchains are shared in cache/.
For lasting selections, edit tracked defconfigs and configs/kernel/*.config.
Changed Linux, U-Boot, or radio configuration inputs trigger native
reconfiguration; unchanged inputs retain native incremental builds. Buildroot
package-selection or toolchain changes require make buildroot-reconfigure
before rebuilding, so stale target contents cannot survive a configuration
change. Save intended Buildroot menu changes in its tracked defconfig before
that command, which removes the selected Buildroot output tree.
ROOTFS_BASELINE=/absolute/path/to/rootfs.sqfs is an explicit incremental
repack option with recorded provenance, not a clean Buildroot rebuild. It
checks the full userspace runtime inventory and the exact module list; an
incomplete baseline is rejected. Inherited target binaries are
not claimed to have been rebuilt with size optimization.
If only stock logging/cron startup scripts are missing, set
ROOTFS_BUSYBOX_BUILD=/path/to/busybox-build to explicitly allow their restoration
from the pinned Buildroot checkout. The repacker checks actual inherited applet/help
bytes, records exact additions, and preserves existing filesystem metadata.
Device targets
make PORT=/dev/ttyUSB0 BAUD=2000000 flash-existing-all
flash-existing-all and its alias flash-all resolve dist/current once, verify that immutable set, and write SPL,
FIT, DTB, radio, kernel and rootfs slot-wise. They never build. build-flash
explicitly builds first. Persist is preserved only when the board already uses
the same layout. The combined image overwrites persist; see
Flash and first boot.
Partial targets (flash-radio, flash-linux, flash-rootfs, flash-dtb,
flash-bootloader, flash-opensbi, and the partial flash-existing-* aliases)
fail closed because the installed companions cannot be proven. There is no
unsafe override. flash-persist and erase also refuse; destructive maintenance
requires an explicit separate procedure.
The manifest checks component and combined-image hashes, radio’s build-time kernel/module/payload/import bindings, and configuration identity. These are host checks; they do not establish a successful hardware boot.
Build variables
Variable |
Use |
|---|---|
|
|
|
Parallel native build jobs |
|
Output and shared-cache roots, defaulting to |
|
Native kernel configuration and image target, defaulting to |
|
Device port and baud rate |
|
Local ESP-IDF paths |
|
U-Boot host interpreter, including env-shebang tools; defaults to the current |
|
Optional extra module-search path for that U-Boot host interpreter |
|
Installed cross-toolchain directory |
|
Dependency-lock release, or explicit local experiment |
|
Source tree for |
|
Explicit experimental ESP-IDF override |
|
Explicit verified rootfs for incremental module repack |
|
Optional existing BusyBox build evidence to restore missing full-service init scripts from pinned Buildroot sources |
Low-level boot-address changes must be coordinated with linker scripts, the layout file and devicetree. See Memory map and Flash layout.