Skip to main content

Build embedded systems with buildroot

This post is a work in progress, so if you find it incomplete and not readable probably it's not finished yet. I prefer to publish a little before than leave a post to rust in my drafts.

Buildroot is an integration system used to obtain complete bootable embedded systems; it uses a KConfig configuration mechanism (the menuconfig thing).

This post is a simple way for me to take notes about it, refer to the official documentation for anything serious.


First of all you need to download the source code with git

$ git clone git://

and then enter in the new created directory.


Now it's possible to configure the system you want to build; if you want to try first a system already configured you can use one of the existing *_defconfig

$ find ./configs -name '*_defconfig'

For example I want to create a test x86_64 system to use with QEmu, so I use qemu_x86_64_defconfig.

$ make qemu_x86_64_defconfig


$ make -j8

All the created files are in output; in our example the files we care about are in output/images/: in this case a bzImage and a root filesystem rootfs.ext2; what remains to do is to launch qemu with the right options:

$ qemu-system-x86_64 \
    -hda output/images/rootfs.ext2 \
    -m 1024 \
    -enable-kvm \
    -kernel linux_image/boot/vmlinuz-3.2.0-23-generic \
    -append 'root=/dev/sda' \
    -net nic,model=virtio -net user,hostfwd=tcp::2222-:22

It's also available a script output/images/ but only with the basic options (no networking for example).

During the package compiling process, Buildroot will record the compiling process via some identification files and save those files to the related directory of the package. All those identification files are:


These identification files mainly control the download, decompression, packaging, configuration, compilation, installation, etc. of this package.

Read docs/manual/rebuilding-packages.txt for more informations (seriously, read it, it's full of information).

Cheat sheet

Save configuration

You can set the file where to save the configuration

Build options ---->
   (configs/whatever_defconfig) Location to save buildroot config

and once exited from menuconfig you can do

$ make savedefconfig

Save kernel configuration

Kernel --->
    (board/vendor/linux.config) Configuration file path


For each package is available a set of commands

  <pkg>                  - Build and install <pkg> and all its dependencies
  <pkg>-source           - Only download the source files for <pkg>
  <pkg>-extract          - Extract <pkg> sources
  <pkg>-patch            - Apply patches to <pkg>
  <pkg>-depends          - Build <pkg>'s dependencies
  <pkg>-configure        - Build <pkg> up to the configure step
  <pkg>-build            - Build <pkg> up to the build step
  <pkg>-graph-depends    - Generate a graph of <pkg>'s dependencies
  <pkg>-dirclean         - Remove <pkg> build directory
  <pkg>-reconfigure      - Restart the build from the configure step
  <pkg>-rebuild          - Restart the build from the build step

Force rebuild target

$ rm -rf output/target
$ find output/ -name ".stamp_target_installed" |xargs rm -rf

Enable keymap

Enable package kbd in order to use loadkeys and the correct localization for your keyboard

       -> Target packages
         -> Hardware handling

Enable ssh

You can connect to it using the redirection in the last line

    -net nic,model=virtio -net user,hostfwd=tcp::2222-:22
$ ssh -p 2222 root@ -o StrictHostKeyChecking=off

Remember to set

PermitRootLogin yes
PermitEmptyPassword yes

into /etc/ssh/sshd_config and restart the service with /etc/init.d/50sshd restart.

Bad enough, with qemu is happened that the machine hangs at boot probably during the ssh-keygen, maybe you can use CONFIG_RANDOM_TRUST_CPU or something indicated here or here or maybe, hit the keyboard a couple times or maybe rng-tools.

In some cases it's possible that sshd doesn't start because the keys are not present, in such case is possible to do

$ ssh-keygen -A -f output/target/ # generate the keys
$ make                            # rebuild the filesystem

Enable X11

This is tricky: for now I was able to make work only the modular X server with a configuration like the following:


Customize filesystem

If you have configuration files that you want to replace you can indicate an overlay directory

    System configuration  --->
         () Root filesystem overlay directories

to use as source.

Another option is to use a post build script: take for example pc_x86_64_bios_defconfig

that uses the following option


to indicate a script to copy boot-related files into the image


set -e

BOARD_DIR=$(dirname "$0")

# Detect boot strategy, EFI or BIOS
if [ -f "$BINARIES_DIR/efi-part/startup.nsh" ]; then
    cp -f "$BOARD_DIR/grub-efi.cfg" "$BINARIES_DIR/efi-part/EFI/BOOT/grub.cfg"
    cp -f "$BOARD_DIR/grub-bios.cfg" "$TARGET_DIR/boot/grub/grub.cfg"

    # Copy grub 1st stage to binaries, required for genimage
    cp -f "$HOST_DIR/lib/grub/i386-pc/boot.img" "$BINARIES_DIR"

Linux kernel

If you want to configure it

$ make linux-menuconfig

and then

$ make linux

to build it.

Build out-of-tree modules

This is as usual

$ cd /path/to/module/code/
$ make KDIR=/path/to/buildroot/output/build/linux-x.y.z/ M=$PWD


  • Official documentation
  • My 6 tips for working with Buildroot


Comments powered by Disqus