Buildroot - hpaluch/hpaluch.github.io GitHub Wiki

Buildroot

To quote: https://buildroot.org/

Buildroot is a simple, efficient and easy-to-use tool to generate embedded Linux systems through cross-compilation.

In other word - it is one of most popular tool to build target system on powerful PC Host Linux. Output is in various formats (rootfs.tar.gz, filesystem images - for example UBI for some embedded system), or even bootable ISO (or hybrid).

Buildroot vs Yocto

There exists also Yocto project with same purpose. Notable points:

  • Buildroot uses familiar KConfig (Linux kernel config) - based on Makefiles using GNU Make as build tool

  • Buildroot does NOT support packages nor system updates (it can just create full image)

  • Important: although Buildroot call components "packages" and they are defined under package/ folder - They are just "recipes" how to build binaries, but not "real" packages.

  • Buildroot names Host packages "host-NAME"

  • Yocto uses custom build tool BitBake written in python

  • Yocto supports several package formats and can even create or update repository. However it handles (understandably) only standard cases for upgrades

  • Yocto names Host packages "native-NAME"

Buildrooot quick start

First we need host system - I will use Debian 12. Install build requirements from

Install required packages:

# Debian 12 host system - amd64

# build-essential includes: binutils bzip2 gcc g++ patch perl
sudo apt-get install build-essential
sudo apt-get install which sed make binutils \
    diffutils bash gzip tar cpio unzip rsync file \
    bc findutils 
# package below required for "make menuconfig"
sudo apt-get install libncurses-dev

My recommended packages:

sudo apt-get install git-core mc tmux curl ncdu

Now we have to download latest stable release on https://buildroot.org/download.html In my case:

cd
curl -fLO https://buildroot.org/downloads/buildroot-2024.08.tar.gz
tar xvf buildroot-2024.08.tar.gz

Now we should decide what build we want to bootstrap. Possible templates are under ~/buildroot-2024.08/configs/. I will use qemu_x86_64_defconfig

NOTE: configs/*_defconfig are basically Makefile fragments so their syntax must be Make compatible - NOT Shell. For example you can see:

BR2_ROOTFS_POST_SCRIPT_ARGS="$(BR2_DEFCONFIG)"

Variables in round brackets are required by GNU Make, not shell.

Now I strongly recommend out of tree build - in my case under /mnt/build

# config name without suffix _defconfig
c=qemu_x86_64
# build target directory:
t=/mnt/build/$c
sudo mkdir -p $t
sudo chown $USER $t
# this creates build tree for our config:
cd ~/buildroot-2024.08
make O=$t ${c}_defconfig

Now you should do everything in your build directory:

$  echo $t

/mnt/build/qemu_x86_64

Now you can tune target details using make menuconfig and then build:

cd $t
make menuconfig

To be able to build bootable ISO you need to enable in menuconfig:

  • BR2_TARGET_SYSLINUX - press / in menuconfig to search and copy & paste this value.
  • BR2_TARGET_ROOTFS_ISO9660
    • ensure that Bootloader is isolinux
  • also select build hybrid image - BR2_TARGET_ROOTFS_ISO9660_HYBRID

Now invoke tmux (it will take time to build) and run make to build image.

NOTE: Although build directory is /mnt/build/qemu_x86_64 buildroot will store Downloaded sources under ~/buildroot-2024.08/dl/

Buildroot will first:

  • build Host packages under build/host-NAME required for building (it is also possible to sometimes use System packages in make menuconfig, but there could be compatibility problems)
  • build environment is created under host directory containing all required headers, libraries, compilers...
  • filesystem Template is build under target, but it is NOT root filesystem !!! (there are different permissions, linker rpath and other important things)
  • official filesystems are created under images

In my case (4 vCPU, 32GB RAM, Azure VM Standard_E4bds_v5), build took 2 hours 35 minutes. Build directory had around 13 GB, download directory ~/buildroot-2024.08/dl/ around 530MB).

Break & Resume build

Because it is regular Makefile system you can break build simply with Ctrl-C (SIGINT).

To resume build simply invoke make in build directory again.

Booting image in QEMU

TODO: Follow: https://buildroot.org/downloads/manual/manual.html#_beyond_buildroot

Backing build directory

Recent GNU tar can suffer when unpacking big archive with lot of items, because it walks linear linked list to find delayed links meaning that unpacking may take forever. I therefore strongly recommend to install BSD tar (called bsdtar) using:

sudo apt-get install libarchive-tools

Resources