5. Build Variants

This repository provides two build variants: release (the default) and debug.

Quick start

make
make debug

The first command builds the release image. The second builds the debug image with debug symbols and verbose firmware. The make release and make debug commands are aliases for the release and debug targets. To run a specific Buildroot target in debug mode, pass the mode explicitly as make MODE=debug <target>.

Toolchain

The cross toolchain is built as a separate stage and consumed as a Buildroot external toolchain, so the release, debug, and programmer variants share one SDK instead of each compiling their own host tools.

In the Nix development shell, the make command is wrapped by a shim: build goals resolve the cached .#toolchain SDK (from Cachix or a local Nix build) and export TOOLCHAIN_SDK automatically. Goals that do not need the cross toolchain, such as configuration, source download, and clean targets, skip the resolution. Two variables control this behavior:

• TOOLCHAIN_SDK=<path>: use the SDK at the given path (any compatible external toolchain).
• SKIP_TOOLCHAIN=1: skip SDK resolution entirely; the internal toolchain is built along with the target.

When TOOLCHAIN_SDK is set, the defconfig merge appends configs/myd_yf135_external_toolchain.fragment plus a generated BR2_TOOLCHAIN_EXTERNAL_PATH fragment, which switches the build to the prebuilt SDK.

To build the relocatable SDK without Nix and reuse it:

make toolchain
make TOOLCHAIN_SDK=$PWD/output/toolchain/sdk debug

The first command builds the SDK from the toolchain-only defconfig, unpacks it to output/toolchain/sdk, and relocates it. The second command consumes that SDK for a debug build.

The compiler cache (ccache) remains shared between variants:

CCACHE_DIR=$PWD/output/ccache make debug

Toolchain defconfig sync

configs/myd_yf135_toolchain_defconfig (stage-1 toolchain-only defconfig) and configs/myd_yf135_external_toolchain.fragment (external-toolchain description merged into target builds) must agree with the main defconfig. The toolchain-defconfig pre-commit hook (support/pre-commit/check-toolchain-defconfig.sh, also available as make regen-toolchain-defconfig) syncs the tracked symbol values from the main defconfig automatically and flags fragment mismatches (libc, kernel headers, C++) for manual update.

Configuration fragments

File	Role
configs/myd_yf135_debug.fragment	Defconfig debug override fragment
board/myd-yf135/linux-debug.fragment	Kernel debug Kconfig fragment
board/myd-yf135/uboot-debug.fragment	U-Boot debug Kconfig fragment
configs/myd_yf135_toolchain_defconfig	Stage-1 toolchain-only defconfig (synced from the main defconfig)
configs/myd_yf135_external_toolchain.fragment	External-toolchain description merged when a prebuilt SDK is used
output/<mode>/myd_yf135_debug_defconfig	Generated debug defconfig (do not edit)

Kernel config

The kernel configuration uses a layered model:

• Release: board/myd-yf135/linux.config
• Debug: release config plus board/myd-yf135/linux-debug.fragment

Super-project externals can inherit this and add project-specific fragments on top.

Firmware verbosity

Component	Release	Debug
TF-A	LOG_LEVEL=0, no STM32MP_SDMMC	LOG_LEVEL=10, STM32MP_SDMMC=1
OP-TEE	CFG_TEE_CORE_LOG_LEVEL=0, no CFG_STM32_EARLY_CONSOLE_UART	CFG_TEE_CORE_LOG_LEVEL=0, CFG_STM32_EARLY_CONSOLE_UART=4
U-Boot	uboot.config (CONFIG_BOOTDELAY=-2, no stop prompt)	uboot.config plus uboot-debug.fragment (CONFIG_BOOTDELAY=3)

U-Boot console silence uses the silent environment variable. This repository reduces noise in release but does not force a fully silent console by default.

Regenerating the debug defconfig

The make debug command performs the merge inline as part of _APPLY_DEFCONFIG; it does not depend on a pre-generated myd_yf135_debug_defconfig.

The make regen-debug-defconfig target is provided for static inspection: it writes the merged defconfig to $(O)/myd_yf135_debug_defconfig to show exactly what the build will apply, including any parent overlays.

make MODE=debug regen-debug-defconfig
less output/debug/myd_yf135_debug_defconfig

Defconfig merger

All variant merges go through support/build/merge-defconfig.py:

merge-defconfig.py <output> <base> [delta1 delta2 ...]

Each delta overrides keys from prior inputs, except for accumulating keys, which are appended space-separated and stack across layers:

• Keys matching *_FRAGMENT_FILES (for example BR2_LINUX_KERNEL_CONFIG_FRAGMENT_FILES or BR2_TARGET_UBOOT_CONFIG_FRAGMENT_FILES).
• BR2_ROOTFS_OVERLAY, allowing parent and Nix-built overlay directories to stack onto the base overlay instead of replacing it.

Both the Makefile and the Nix build (nix/build.nix) call this script, so shell-mode and Nix builds produce identical merged defconfigs.

Super-project integration

For details on passing BR2_EXTERNAL_EXTRA, layered defconfig stacking from parent overlays, and the mkProject Nix interface, see Layered defconfig stacking.