Readme
ReadmeNov 19, 2026

Buildroot: custom boards with BR2_EXTERNAL

keep your board, packages and configs outside the Buildroot tree

1. Dependencies (Debian/Ubuntu)

bash
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

bash
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

text
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

text
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)

text
source "$BR2_EXTERNAL_MY_BOARDS_PATH/package/mytool/Config.in"

external.mk (pulls in every package makefile)

make
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
  • .mk and 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:

bash
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):

text
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):

bash
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:

bash
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):

text
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):

text
BR2_LINUX_KERNEL_INTREE_DTS_NAME="vendor/my-board"

Out-of-tree DTS (lives in your external tree):

text
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:

text
BR2_GLOBAL_PATCH_DIR="$(BR2_EXTERNAL_MY_BOARDS_PATH)/patches"
text
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

text
config BR2_PACKAGE_MYTOOL
	bool "mytool"
	help
	  My tool.

package/mytool/mytool.mk, local C sources, no download:

make
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 plain gcc, otherwise you get a host binary.
  • Use $(autotools-package), $(cmake-package) or $(meson-package) instead of generic-package for upstream projects that use those build systems.
  • Libraries: MYTOOL_DEPENDENCIES = readline in the .mk plus select BR2_PACKAGE_READLINE in Config.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/src into local.mk and set BR2_PACKAGE_OVERRIDE_FILE accordingly.

Enable it in menuconfig under External options, or add BR2_PACKAGE_MYTOOL=y to the defconfig.

11. What to rebuild after a change

ChangedCommand
overlay, post-build or post-image script, genimage.cfgmake
a package's sourcesmake <pkg>-rebuild && make
a package's options or .mkmake <pkg>-reconfigure && make
kernel configmake linux-reconfigure && make
kernel sources, DTS, kernel patchesmake linux-rebuild && make
U-Boot config or sourcesmake uboot-reconfigure && make
architecture, libc or toolchainmake clean && make
Buildroot versionmake 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):

bash
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:

bash
sfdisk -l images/sdcard.img
sudo losetup -fP --show images/sdcard.img      # then mount /dev/loopXpN, losetup -d when done

13. Flashing

bash
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 match name: in external.desc (NAME gives BR2_EXTERNAL_NAME_PATH, XF_TREE gives BR2_EXTERNAL_NAME_TREE_PATH).
  • Old paths in the build log: .config still holds paths from before. Reload with make myboard_defconfig and check with grep -n board/ .config.
  • Permission denied on a script: chmod +x post-build.sh.
  • No such file in genimage: a file named in image = 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.sh uses an empty rootpath, so use it.
  • Rootfs image does not fit: BR2_TARGET_ROOTFS_EXT2_SIZE larger than its partition, or smaller than the content.
  • EXT4-fs error ... checksum invalid or no journal: kernel lacks CONFIG_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), wrong root=, or missing rootwait.
  • 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_EXTERNAL ignored: it is cached in output/.br2-external.mk. Pass BR2_EXTERNAL=... again together with the defconfig target.
  • Version string of the external tree looks like Buildroot's: it comes from git describe of the directory, so keep the external tree in its own git repository (and tag it).
  • Read the error above the tail: the final Error 2 is noise. Find the first error:. For debugging use make V=1 2>&1 | tee build.log; per-package build trees are in output/build/<pkg>-<version>/.