Buildroot: custom boards with BR2_EXTERNAL
keep your board, packages and configs outside the Buildroot tree
1. Dependencies (Debian/Ubuntu)
sudo apt install build-essential git wget cpio unzip rsync bc file \
libncurses-dev libssl-dev python3 perl patch gzip bzip2 tar
Optional, needed by some boards: swig, python3-dev, device-tree-compiler, qemu-system-arm.
2. Sources
git clone https://gitlab.com/buildroot.org/buildroot.git
cd buildroot
git tag | tail # pick a release tag, LTS releases are safest
git checkout <release> # e.g. 2025.02
Or a tarball from buildroot.org: tar xf buildroot-<release>.tar.xz.
Never edit files inside the Buildroot tree. Everything board-specific lives in the external tree, so Buildroot can be upgraded by changing one checkout.
3. External tree layout
my-external/
├── external.desc
├── external.mk
├── Config.in
├── configs/
│ └── myboard_defconfig
├── board/vendor/myboard/
│ ├── linux.config # full kernel .config (or fragment)
│ ├── my-board.dts # optional out-of-tree DTS
│ ├── genimage.cfg
│ ├── post-build.sh
│ ├── rootfs_overlay/ # copied over the target rootfs as is
│ └── patches/ # optional, see section 9
├── patches/ # global patch dir (optional)
└── package/
└── mytool/
├── Config.in
├── mytool.mk
└── src/
4. The three mandatory files
external.desc
name: MY_BOARDS
desc: Custom boards and packages
name may only contain [A-Za-z0-9_]. It defines the variable BR2_EXTERNAL_MY_BOARDS_PATH.
Config.in (menu entries, shown under External options)
source "$BR2_EXTERNAL_MY_BOARDS_PATH/package/mytool/Config.in"
external.mk (pulls in every package makefile)
include $(sort $(wildcard $(BR2_EXTERNAL_MY_BOARDS_PATH)/package/*/*.mk))
Both can be empty if there are no packages, but the files must exist.
Path syntax differs by file type:
Config.in(Kconfig):$BR2_EXTERNAL_MY_BOARDS_PATH.mkand defconfig:$(BR2_EXTERNAL_MY_BOARDS_PATH)
Paths in a defconfig without the variable are relative to the Buildroot top directory, not to your tree.
5. Board defconfig
Start from the closest stock board instead of from scratch:
make list-defconfigs | grep -i <soc-or-vendor>
make <stock>_defconfig
make menuconfig
make savedefconfig BR2_DEFCONFIG=/path/to/my-external/configs/myboard_defconfig
Typical aarch64 result (values are placeholders):
BR2_aarch64=y
BR2_cortex_a53=y
BR2_TOOLCHAIN_BUILDROOT_MUSL=y
BR2_OPTIMIZE_S=y
BR2_TARGET_GENERIC_HOSTNAME="myboard"
BR2_TARGET_GENERIC_GETTY_PORT="ttyS0"
BR2_ROOTFS_OVERLAY="$(BR2_EXTERNAL_MY_BOARDS_PATH)/board/vendor/myboard/rootfs_overlay"
BR2_ROOTFS_POST_BUILD_SCRIPT="$(BR2_EXTERNAL_MY_BOARDS_PATH)/board/vendor/myboard/post-build.sh"
BR2_ROOTFS_POST_IMAGE_SCRIPT="support/scripts/genimage.sh"
BR2_ROOTFS_POST_SCRIPT_ARGS="-c $(BR2_EXTERNAL_MY_BOARDS_PATH)/board/vendor/myboard/genimage.cfg"
BR2_LINUX_KERNEL=y
BR2_LINUX_KERNEL_CUSTOM_VERSION=y
BR2_LINUX_KERNEL_CUSTOM_VERSION_VALUE="6.12.10"
BR2_LINUX_KERNEL_USE_CUSTOM_CONFIG=y
BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE="$(BR2_EXTERNAL_MY_BOARDS_PATH)/board/vendor/myboard/linux.config"
BR2_LINUX_KERNEL_DTS_SUPPORT=y
BR2_LINUX_KERNEL_INTREE_DTS_NAME="vendor/my-board"
BR2_LINUX_KERNEL_INSTALL_TARGET=y
BR2_TARGET_UBOOT=y
BR2_TARGET_UBOOT_BUILD_SYSTEM_KCONFIG=y
BR2_TARGET_UBOOT_CUSTOM_VERSION=y
BR2_TARGET_UBOOT_CUSTOM_VERSION_VALUE="2025.01"
BR2_TARGET_UBOOT_BOARD_DEFCONFIG="myboard"
BR2_TARGET_UBOOT_NEEDS_DTC=y
BR2_TARGET_ROOTFS_EXT2=y
BR2_TARGET_ROOTFS_EXT2_4=y
BR2_TARGET_ROOTFS_EXT2_SIZE="200M"
BR2_PACKAGE_HOST_GENIMAGE=y
BR2_TARGET_ROOTFS_EXT2_4=y selects ext4 (otherwise you get rootfs.ext2). support/scripts/genimage.sh ships with Buildroot, so no custom post-image script is needed.
6. Build workflow
Out-of-tree build directory (recommended, Buildroot stays clean):
make -C buildroot O=$PWD/out/myboard \
BR2_EXTERNAL=$PWD/my-external myboard_defconfig
cd out/myboard
make menuconfig
make
Inside out/myboard the generated wrapper Makefile remembers the source tree and the external tree, so plain make is enough from now on.
Several external trees: BR2_EXTERNAL=/path/a:/path/b.
Saving changes. Treat the defconfig as the source of truth, never the raw .config:
make savedefconfig # writes back to configs/myboard_defconfig
make linux-menuconfig
make linux-update-defconfig # saves to the custom kernel config file
make uboot-menuconfig
make uboot-update-defconfig
Results are in images/: Image, *.dtb, u-boot*.bin, rootfs.ext4, sdcard.img.
7. Image layout (genimage)
board/vendor/myboard/genimage.cfg for an SD card or eMMC (MBR, FAT boot, ext4 root):
image boot.vfat {
vfat { files = { "Image", "my-board.dtb" } }
size = 32M
}
image sdcard.img {
hdimage { }
partition u-boot {
in-partition-table = "no"
image = "u-boot.bin"
offset = 8K # SoC specific, take it from the SoC docs
}
partition boot {
partition-type = 0xC
bootable = "true"
image = "boot.vfat"
offset = 4M
}
partition rootfs {
partition-type = 0x83
image = "rootfs.ext4"
}
}
Every image = must exist in images/ before genimage runs. For GPT use hdimage { partition-table-type = "gpt" }. A/B layouts are two rootfs partitions with the same image.
Bootloader location and offsets differ for every SoC. Take them from the vendor docs or from the stock Buildroot board closest to yours.
8. Device tree
In-tree DTS (already in the kernel):
BR2_LINUX_KERNEL_INTREE_DTS_NAME="vendor/my-board"
Out-of-tree DTS (lives in your external tree):
BR2_LINUX_KERNEL_CUSTOM_DTS_PATH="$(BR2_EXTERNAL_MY_BOARDS_PATH)/board/vendor/myboard/my-board.dts"
Both can be combined. The custom DTS may #include in-tree .dtsi files.
9. Patches
Global patch directory, applied to any package by name:
BR2_GLOBAL_PATCH_DIR="$(BR2_EXTERNAL_MY_BOARDS_PATH)/patches"
patches/linux/0001-fix-something.patch
patches/uboot/0001-board-support.patch
patches/busybox/0001-tweak.patch
Versioned subdirectories (patches/linux/6.12.10/) are also supported. Package names: kernel is linux, U-Boot is uboot.
10. Adding your own package
package/mytool/Config.in
config BR2_PACKAGE_MYTOOL
bool "mytool"
help
My tool.
package/mytool/mytool.mk, local C sources, no download:
MYTOOL_VERSION = 1.0
MYTOOL_SITE = $(BR2_EXTERNAL_MY_BOARDS_PATH)/package/mytool/src
MYTOOL_SITE_METHOD = local
MYTOOL_LICENSE = Proprietary
define MYTOOL_BUILD_CMDS
$(TARGET_CC) $(TARGET_CFLAGS) $(TARGET_LDFLAGS) \
-o $(@D)/mytool $(@D)/main.c
endef
define MYTOOL_INSTALL_TARGET_CMDS
$(INSTALL) -D -m 0755 $(@D)/mytool $(TARGET_DIR)/usr/bin/mytool
endef
$(eval $(generic-package))
Rules:
- Always compile with
$(TARGET_CC), never plaingcc, otherwise you get a host binary. - Use
$(autotools-package),$(cmake-package)or$(meson-package)instead ofgeneric-packagefor upstream projects that use those build systems. - Libraries:
MYTOOL_DEPENDENCIES = readlinein the.mkplusselect BR2_PACKAGE_READLINEinConfig.in. - Sources from git:
MYTOOL_SITE = https://example.com/mytool.git,MYTOOL_SITE_METHOD = git,MYTOOL_VERSION = <commit>. - Work on an external source checkout without copying it: put
MYTOOL_OVERRIDE_SRCDIR = /path/to/srcintolocal.mkand setBR2_PACKAGE_OVERRIDE_FILEaccordingly.
Enable it in menuconfig under External options, or add BR2_PACKAGE_MYTOOL=y to the defconfig.
11. What to rebuild after a change
| Changed | Command |
|---|---|
| overlay, post-build or post-image script, genimage.cfg | make |
| a package's sources | make <pkg>-rebuild && make |
a package's options or .mk | make <pkg>-reconfigure && make |
| kernel config | make linux-reconfigure && make |
| kernel sources, DTS, kernel patches | make linux-rebuild && make |
| U-Boot config or sources | make uboot-reconfigure && make |
| architecture, libc or toolchain | make clean && make |
| Buildroot version | make clean && make |
make <pkg>-dirclean wipes one package completely. make clean removes all build output but keeps .config and the download cache. Set BR2_DL_DIR and BR2_CCACHE=y to make repeated full builds much faster.
12. Testing
aarch64 under QEMU (generic virt machine, tests kernel and userspace but not your SoC):
qemu-system-aarch64 -M virt -cpu cortex-a72 -m 512 -nographic -snapshot \
-kernel images/Image \
-drive file=images/sdcard.img,if=none,format=raw,id=hd0 \
-device virtio-blk-device,drive=hd0 \
-append "root=/dev/vda2 rootwait console=ttyAMA0"
-snapshot keeps the image untouched. Use the root= partition number from your genimage layout. The kernel needs virtio-blk, CONFIG_ARCH_VIRT, PL011 console and your root filesystem built in (=y). For real hardware keep the UART console attached; without it boot problems are invisible.
Inspect an image without booting:
sfdisk -l images/sdcard.img
sudo losetup -fP --show images/sdcard.img # then mount /dev/loopXpN, losetup -d when done
13. Flashing
lsblk # double check the device name
sudo dd if=images/sdcard.img of=/dev/sdX bs=4M conv=fsync status=progress
sync
This destroys everything on the target device. For eMMC use the vendor tool or a USB/UMS boot mode if the SoC supports it.
Common pitfalls
can't open file "/package/.../Config.in": variable name does not matchname:inexternal.desc(NAMEgivesBR2_EXTERNAL_NAME_PATH,XF_TREEgivesBR2_EXTERNAL_NAME_TREE_PATH).- Old paths in the build log:
.configstill holds paths from before. Reload withmake myboard_defconfigand check withgrep -n board/ .config. Permission deniedon a script:chmod +x post-build.sh.No such filein genimage: a file named inimage =was never produced (ext4 not enabled, ext2 variant selected, U-Boot not built).- Data partition full of the whole rootfs: a custom post-image script passed
${TARGET_DIR}as genimage--rootpath.support/scripts/genimage.shuses an empty rootpath, so use it. - Rootfs image does not fit:
BR2_TARGET_ROOTFS_EXT2_SIZElarger than its partition, or smaller than the content. EXT4-fs error ... checksum invalidorno journal: kernel lacksCONFIG_CRYPTO_CRC32C=y/CONFIG_LIBCRC32C=y, or the image file was corrupted by an unclean QEMU shutdown.- Kernel panics with
Unable to mount root fs: block driver or filesystem built as a module (modules are not loaded before the root is mounted), wrongroot=, or missingrootwait. - Package fails on musl: missing
execinfo.h,error.h,fts.h, glibc-only calls. Add a patch,-D_GNU_SOURCE, or switch the toolchain to glibc. BR2_EXTERNALignored: it is cached inoutput/.br2-external.mk. PassBR2_EXTERNAL=...again together with the defconfig target.- Version string of the external tree looks like Buildroot's: it comes from
git describeof the directory, so keep the external tree in its own git repository (and tag it). - Read the error above the tail: the final
Error 2is noise. Find the firsterror:. For debugging usemake V=1 2>&1 | tee build.log; per-package build trees are inoutput/build/<pkg>-<version>/.