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 words - 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"

One reason to prefer Buildroot is that NXP LayerScape SDK moved from Yocto to Buildroot, so if you plan to use NXP LS processors (aarch64) it is better to learn Buildroot than Yocto.

Buildrooot quick start

First we need host system - I will use Debian 12 and openSUSE LEAP 15.6. 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

# on openSUSE LEAP 15.6:
sudo zypper in -t pattern devel_C_C++
sudo zypper in bc cpio tar gzip unzip rsync file findutils

My recommended packages:

# on Debian 12:
sudo apt-get install git-core mc tmux curl ncdu
# on openSUSE LEAP 15.6:
sudo zypper in 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

NOTE: For dual-stack (IPv4 + IPv6) environment: I encountered serious slowdown while downloading files, because some mirrors were not reachable via IPv6 (although they have IPv6 DNS records). As workaround I added -4 to wget command with option:

BR2_WGET="wget -nd -t 3 -4"

To be able to use QEMU without GUI (just serial console) you need to - create new file ~/buildroot-2024.08/fs/iso9660/isolinux2.cfg with parameter console=ttyS0:

default 1
label 1
      kernel __KERNEL_PATH__
      initrd __INITRD_PATH__
      append root=/dev/sr0 console=ttyS0

And ensure that you use that path in:

BR2_TARGET_ROOTFS_ISO9660_BOOT_MENU="fs/iso9660/isolinux2.cfg"

NOTE: To just download all sources (to ensure that build will not fail in the middle) you can use source target:

make source

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

Build times (I first run make source to download everything and then time make to measure build time):

  • Azure Debian 12 VM: (4 vCPU, 32GB RAM, Standard_E4bds_v5):
    • build ("real time") took 51 minutes 38 seconds
  • bare metal openSUSE LEAP 15.6: MSI Cubi, 10 cores (2 of them fast, with 2 threads each), 12 threads, 32GB RAM, 500GB NVMe SSD:
    • build ("real time") took (while playing music and browsing web): 19 minutes 55 seconds

Build directory had around 13 GB under Debian, 9.4 GB on openSUSE, 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

First install QEMU using:

# Debian 12
sudo apt-get install qemu-system-x86

# openSUSE LEAP 15.6:
sudo zypper in qemu-x86

Now you can run QEMU with simple:

qemu-system-x86_64 -nographic -cdrom images/rootfs.iso9660 \
   -netdev user,id=u1 -device virtio-net,netdev=u1

Use root as login, without password. Press Ctrl-a followed by just x (without Ctrl) to exit QEMU). Or press Ctrl-a followed by h to get list of QEMU console commands.

If you have /dev/kvm available you can append -accel kvm to speed-up QEMU considerably.

Resources:

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