Buildroot

Introduction

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

It uses the Linux Kconfig configuration system, allowing easy selection of system content. The Makefile will include a .config file generated by Kconfig. The content of this file will determine what should be built.

It is relatively easy from there to add your own programs so your entire build process is automated.

Home website : http://www.buildroot.net/

The Buildroot user manual can help you better understand how Buildroot works.

For our Linux4sam distributions, we actually use two buildroot trees, which work in conjunction. One tree is named buildroot-mchp, and it's available on github buildroot-mchp repository. This repository buildroot-mchp is normally on top of a specific mainline Buildroot version, with none to very few patches on top, just to fix small issues from upstream Buildroot.
We always build our Buildroot together with a second tree, named buildroot-external-microchip, available on github buildroot-external-microchip repository, which is a specific Buildroot External that provides our specific packages , libs, etc. and it also includes the latest configuration for our boards. The buildroot External is some kind of Yocto layer if you are familiar with this, but does not have the full capabilities of a Yocto layer. We can see it as an addendum to the original buildroot. An External will provide additional files and packages for our distribution.
While the mainline Buildroot builds correctly, it does not offer the full richness of a linux4sam distribution. For a full linux4sam distribution, we use this External to compliment the mainline Buildroot (or buildroot-mchp) with additional features specific for our linux4sam distribution.

For our linux4sam distribution , we always use our buildroot-mchp tree together with buildroot-external-microchip, and this is the way we recommend to everyone.

In theory , one can try to build our External with the upstream Buildroot repository, but you might miss some fixes which we made on top of upstream buildroot and pushed to our buildroot-mchp. Also, in theory, our External can work with different versions of Buildroot upstream. However we do not test nor support this out of the box. Because in upstream buildroot, packages are changed, removed, added from one version to another, you might face build issues that we did not test during our linux4sam releases. To have a smooth experience, you have to checkout our specific tandem tags which we place on each repository in our trees, meaning pick one of our releases, and select on both trees the same tag for a correct build.

Currently the Buildroot can build

at91bootstrap
u-boot-mchp
linux-mchp
A cross-compiler optimized for your SoC
Root filesystems of different types
Bootable SD card

How to build Buildroot for AT91

Prerequisites

Host build system should be a Linux system with necessary software installed.

In addition to these required packages, you should also install libssl-dev:

$ sudo apt-get install libssl1.0-dev

or, depending on your host distribution:

$ sudo apt-get install libssl-dev

You can install missing packages using yum install with Fedora or apt-get install with Ubuntu or Debian. These commands may require root privileges or being in a correct sudoers group.

Check if additional package are needed in this FAQ entry.

Get sources

To get the source code, you have to clone the buildroot-mchp and buildroot-external-microchip repositories. buildroot-mchp is a fork of Buildroot with a minimal amount of patches, only the ones which have not hit the mainline yet. The external tree provides stuff which won't hit the mainline: additional defconfigs and packages dedicated to our demos.

$ git clone https://github.com/linux4microchip/buildroot-mchp.git
Cloning into 'buildroot-mchp'...
remote: Enumerating objects: 478163, done.
remote: Counting objects: 100% (19/19), done.
remote: Compressing objects: 100% (15/15), done.
remote: Total 478163 (delta 7), reused 11 (delta 4), pack-reused 478144
Receiving objects: 100% (478163/478163), 105.79 MiB | 3.39 MiB/s, done.
Resolving deltas: 100% (320697/320697), done.

$ ls buildroot-mchp/
arch  board  boot  CHANGES  Config.in  Config.in.legacy  configs  COPYING  DEVELOPERS  docs  fs  linux  Makefile  Makefile.legacy  package  README  support  system  toolchain  utils


$ git clone https://github.com/linux4microchip/buildroot-external-microchip.git
Cloning into 'buildroot-external-microchip'...
remote: Counting objects: 571, done.
remote: Compressing objects: 100% (159/159), done.
remote: Total 571 (delta 217), reused 288 (delta 170), pack-reused 225
Receiving objects: 100% (571/571), 94.41 KiB | 76.00 KiB/s, done.
Resolving deltas: 100% (332/332), done.

$ ls buildroot-external-microchip/
board  Config.in  configs  COPYING  docs  external.desc  external.mk  package  patches  README.md  system

The source code has been taken from the master branch which is pointing to the latest version of buildroot-mchp and buildroot-external-microchip. We advise you to use linux4sam tags to be sure that there is no mismatch between the versions of these two repositories.

You can list them and use one of them by doing this:

: Buildroot external microchip tree (buildroot-at91 too being migrated) is now part of linux4microchip, hence the tags on this repo are linux4microchip-*** named.

$ cd buildroot-external-microchip/
$ git tag | grep linux4microchip
linux4microchip+fpga-2022.11
linux4microchip+fpga-2023.02
linux4microchip+fpga-2023.02.1
linux4microchip+fpga-2023.06
linux4microchip+fpga-2023.09
linux4microchip+fpga-2024.02
linux4microchip-2022.10
linux4microchip-2022.10-rc1
linux4microchip-2022.10-rc2
linux4microchip-2022.10-rc3
linux4microchip-2022.10-rc4
linux4microchip-2023.04
linux4microchip-2023.04-rc1
linux4microchip-2023.04-rc2
linux4microchip-2023.10
linux4microchip-2023.10-rc1
linux4microchip-2023.10-rc2
linux4microchip-2023.10-rc3
linux4microchip-2023.10-rc4
linux4microchip-2024.04-rc1
linux4microchip-2024.04-rc2
linux4microchip-2024.04

$ git checkout linux4microchip-2024.04 -b buildroot-external-microchip-linux4microchip-2024.04

$ cd ../buildroot-mchp/
$ git tag | grep linux4microchip
linux4microchip-2024.04-rc2
linux4microchip-2024.04

$ git checkout linux4microchip-2024.04 -b buildroot-at91-linux4microchip-2024.04

Build the rootfs image

Assuming you are at the Buildroot root directory, you'll find a configs folder containing several default configurations. If you are familiar with kernel configuration, you'll see that it works in the same way.

For the same board, several defconfig files are provided inside the buildroot-at91. These defconfigs are from upstream and, as said above, without the richness of a full linux4sam release. They can be used for a minimal test image.

atmel_[soc]_xplained_defconfig provides at91bootstrap, u-boot, the kernel image and dtb files, a very basic rootfs for NAND flash memory.
atmel_[soc]_xplained_mmc_defconfig provides the same stuff but for SD card. Moreover a SD card image is done to ease the creation of the bootable SD card.
atmel_[soc]_xplained_dev_defconfig and atmel_[soc]_xplained_mmc_dev_defconfig provide a rootfs with additional tools to use SoC devices (I2C, CAN, audio, etc.).

The external provides extra defconfigs in its own configs folder:

[soc]_[board]_headless_defconfig provides barely the same stuff as atmel_[soc]_xplained_mmc_dev_defconfig plus AWS greengrass or other command-line tools, but with no graphics related packages.
[soc]_[board]_graphics_defconfig provides the same stuff plus a full graphics (EGT) demo.

All these defconfigs target the SD card as boot media.

If you want to build the basic rootfs image we provide for sama5d2-xplained for example, you'll have to do:

$ make atmel_sama5d2_xplained_mmc_defconfig

BR2_EXTERNAL is not mandatory if you don't plan to use the content of the external tree

If you want to build the linux4sam demo rootfs image we provide for sama5d2-xplained, you'll have to do:

$ BR2_EXTERNAL=../buildroot-external-microchip/ make sama5d2_xplained_graphics_defconfig

Then you can build the rootfs:

$ BR2_EXTERNAL=../buildroot-external-microchip/ make

Once compilation is done, have a look to output/images to see what has been generated:

$ ls output/images/
at91bootstrap.bin          rootfs.ext2                       sama5d2_xplained_isc.dtbo     sama5d2_xplained_pda4.dtbo   sama5d2_xplained_qspi.dtbo                    zImage
at91-sama5d2_xplained.dtb  rootfs.ext4                       sama5d2_xplained.itb          sama5d2_xplained_pda5.dtbo   sama5d2_xplained-sdcardboot-uboot-3.9.0.bin
boot.bin                   rootfs.tar                        sama5d2_xplained_ov7670.dtbo  sama5d2_xplained_pda7b.dtbo  sdcard.img
boot.vfat                  sama5d2_xplained_i2s0_proto.dtbo  sama5d2_xplained_ov7740.dtbo  sama5d2_xplained_pda7.dtbo   u-boot.bin

You can have a look at the Create a SD card with the demo page to create an SD card from the sdcard.img file. If you want to flash NAND or whatever memory you want with Sam-Ba, please go to the Using SAM-BA to flash components to board section of your board.

Cross toolchain

While creating the rootfs, Buildroot will build a cross toolchain (or will download or use one present on your machine). You can find it under output/host/usr:

$ ls output/host/usr/bin
2to3                                             arm-linux-gcc-ranlib  fdtoverlay                libpng-config     python3.7m-config
2to3-3.7                                         arm-linux-gcov        fdtput                    libtool           python3-config
aclocal                                          arm-linux-gcov-dump   fincore                   libtoolize        python-config
aclocal-1.15                                     arm-linux-gcov-tool   findmnt                   linux32           python-freeze-importlib
arm-buildroot-linux-gnueabihf-addr2line          arm-linux-gdb         fixqt4headers.pl          linux64           pyvenv
arm-buildroot-linux-gnueabihf-ar                 arm-linux-gprof       flex                      linux-dtc         qdbuscpp2xml
arm-buildroot-linux-gnueabihf-as                 arm-linux-ld          flex++                    logger            qdbusxml2cpp
arm-buildroot-linux-gnueabihf-c++                arm-linux-ld.bfd      flock                     look              qlalr
arm-buildroot-linux-gnueabihf-c++.br_real        arm-linux-nm          gapplication              lrelease          qmake
arm-buildroot-linux-gnueabihf-cc                 arm-linux-objcopy     gawk                      lsattr            qmlcachegen
arm-buildroot-linux-gnueabihf-cc.br_real         arm-linux-objdump     gdbus                     lsblk             qmlimportscanner
arm-buildroot-linux-gnueabihf-c++filt            arm-linux-ranlib      gdbus-codegen             lscpu             qmllint
arm-buildroot-linux-gnueabihf-cpp                arm-linux-readelf     gdk-pixbuf-csource        lsipc             qmlmin
arm-buildroot-linux-gnueabihf-cpp.br_real        arm-linux-size        gdk-pixbuf-pixdata        lslocks           qt.conf
arm-buildroot-linux-gnueabihf-elfedit            arm-linux-strings     gdk-pixbuf-query-loaders  lsmem             qvkgen
arm-buildroot-linux-gnueabihf-g++                arm-linux-strip       gdk-pixbuf-thumbnailer    lsns              rake
arm-buildroot-linux-gnueabihf-g++.br_real        attr                  gem                       lupdate           rcc
arm-buildroot-linux-gnueabihf-gcc                autoconf              genbrk                    lzip              rdjpgcom
arm-buildroot-linux-gnueabihf-gcc-7.4.0          autoheader            gencfu                    m4                rdoc
arm-buildroot-linux-gnueabihf-gcc-7.4.0.br_real  autom4te              gencnval                  makeconv          rename
arm-buildroot-linux-gnueabihf-gcc-ar             automake              gendict                   makedevs          renice
arm-buildroot-linux-gnueabihf-gcc.br_real        automake-1.15         genimage                  mcookie           reset
arm-buildroot-linux-gnueabihf-gcc-nm             autopoint             genrb                     meson             rev
arm-buildroot-linux-gnueabihf-gcc-ranlib         autoreconf            getfacl                   mk_cmds           ri
arm-buildroot-linux-gnueabihf-gcov               autoscan              getfattr                  mkenvimage        ruby
arm-buildroot-linux-gnueabihf-gcov-dump          autoupdate            getopt                    mkimage           script
arm-buildroot-linux-gnueabihf-gcov-tool          bison                 gettextize                mkpasswd          scriptreplay
arm-buildroot-linux-gnueabihf-gdb                cal                   gio                       moc               setarch
arm-buildroot-linux-gnueabihf-gprof              captoinfo             gio-querymodules          mount             setfacl
arm-buildroot-linux-gnueabihf-ld                 chacl                 glib-compile-resources    mountpoint        setfattr
arm-buildroot-linux-gnueabihf-ld.bfd             chattr                glib-compile-schemas      msgfmt            setsid
arm-buildroot-linux-gnueabihf-nm                 choom                 glib-genmarshal           msgmerge          sip
arm-buildroot-linux-gnueabihf-objcopy            cjpeg                 glib-gettextize           namei             smtpd.py
arm-buildroot-linux-gnueabihf-objdump            clear                 glib-mkenums              ncurses6-config   smtpd.py.7
arm-buildroot-linux-gnueabihf-ranlib             cmake                 gobject-query             ninja             swig
arm-buildroot-linux-gnueabihf-readelf            col                   gperf                     node              swig3.0
arm-buildroot-linux-gnueabihf-run                colcrt                gresource                 npm               syncqt.pl
arm-buildroot-linux-gnueabihf-size               colrm                 gsettings                 npx               tabs
arm-buildroot-linux-gnueabihf-strings            column                gtester                   openssl           tic
arm-buildroot-linux-gnueabihf-strip              compile_et            gtester-report            patchelf          toe
arm-linux-addr2line                              convert-dtsv0         hexdump                   pcre-config       toolchain-wrapper
arm-linux-ar                                     cpack                 i386                      pcregrep          torque
arm-linux-as                                     c_rehash              icu-config                pcretest          tput
arm-linux-c++                                    ctest                 icuinfo                   pkgconf           tset
arm-linux-c++.br_real                            djpeg                 ifnames                   pkg-config        uic
arm-linux-cc                                     dmesg                 infocmp                   pkgdata           umount
arm-linux-cc.br_real                             dtc                   infotocap                 prlimit           uname26
arm-linux-c++filt                                dtdiff                ipcmk                     pydoc             utmpdump
arm-linux-cpp                                    dumpimage             ipcrm                     pydoc3            uuidgen
arm-linux-cpp.br_real                            easy_install          ipcs                      pydoc3.7          uuidparse
arm-linux-elfedit                                easy_install-2.7      irb                       python            whereis
arm-linux-g++                                    easy_install-3.7      isosize                   python2           wrjpgcom
arm-linux-g++.br_real                            eject                 jpegtran                  python2.7         x86_64
arm-linux-gcc                                    erb                   kill                      python2.7-config  xgettext
arm-linux-gcc-7.4.0                              faked                 kmod                      python2-config    xmlwf
arm-linux-gcc-7.4.0.br_real                      fakeroot              last                      python3           yacc
arm-linux-gcc-ar                                 fallocate             lastb                     python3.7
arm-linux-gcc.br_real                            fdtdump               lconvert                  python3.7-config
arm-linux-gcc-nm                                 fdtget                libpng16-config           python3.7m

If you do a make clean, you will delete the rootfs but also the cross toolchain. You can save the cross toolchain in another place. Moreover you can tell Buildroot to use it to save time for next compilations. To do it run make menuconfig then go to the Toolchain menu. Then select External toolchain as Toolchain type, Custom toolchain as Toolchain, Pre-installed toolchain as Toolchain origin. Finally set Toolchain path and Toolchain prefix.

Customizing Buildroot

Before building the rootfs image, you may want to customize it: adding/removing packages, modifying component configurations such as busybox and uclibc, generate the kernel, etc.

Customizing Busybox / Linux / U-boot / uClibc configuration

All the explanations are available in the Buildroot manual Configuration of other components section.

Adding/removing packages from the rootfs

You can easily add or remove packages from the rootfs. You simply have to do:

BR2_EXTERNAL=../buildroot-external-microchip/ make menuconfig

and to go to the Package Selection for the target menu. Packages are sorted by categories:

You simply have to go in the desired category and to select or deselect the packages you want. Once done, you can build your rootfs.

If you have already done a build and you want to remove packages, you may have to do make clean and to rebuild the whole rootfs to be sure that the packages will be removed.

Updating the rootfs for another nand flash device

The rootfs are configured to run on the nand flash device present on atmel boards. If you use another one you may have to update some parameters. To do it, run make menuconfig and go to Filesystem images:

For a jffs2 root filesystem, you may have to update the page and erase size from Flash Type.

For a ubifs root filesystem, you may have to update the UBI logical erase block size, the UBI minimum I/O size, the Maximum LEB count, the UBI physical erase block size and the UBI sub-page size. You can find more information about these parameters in the ubi documentation.

Add your own software to Buildroot

Builroot is basically a big set of makefiles so you will have to follow some steps to insert your own application to the cross-building system. You should have a look at the official documentation since the procedure depends on the build system used.

How to build Buildroot for sama7d65

Prerequisites

Host build system should be a Linux system with necessary software installed: http://buildroot.uclibc.org/downloads/manual/manual.html#requirement

Note You can install missing packages using yum install with Fedora or apt install with Ubuntu or Debian. These commands may require root privileges or being in a correct sudoers group.

Get sources

To get the source code, you have to clone the buildroot-at91 and buildroot-external-microchip repositories. buildroot-at91 is a fork of Buildroot with a minimal number of patches. The external tree provides changes which will not hit the mainline: additional defconfigs files and packages dedicated to our demos.

$ git clone https://github.com/linux4sam/buildroot-at91.git -b 2024.02-mchp
Cloning into 'buildroot-at91'...
remote: Enumerating objects: 463728, done.
remote: Counting objects: 100% (83926/83926), done.
remote: Compressing objects: 100% (30247/30247), done.
remote: Total 463728 (delta 53436), reused 83881 (delta 53426), pack-reused 379802
Receiving objects: 100% (463728/463728), 102.44 MiB | 10.50 MiB/s, done.
Resolving deltas: 100% (313672/313672), done.

$ ls buildroot-at91/
arch board boot CHANGES Config.in Config.in.legacy configs COPYING DEVELOPERS docs
fs linux Makefile Makefile.legacy package README support system toolchain utils

$ git clone https://github.com/linux4sam/buildroot-external-microchip.git
Cloning into 'buildroot-external-microchip'...
remote: Enumerating objects: 7753, done.
remote: Counting objects: 100% (7753/7753), done.
remote: Compressing objects: 100% (1634/1634), done.
remote: Total 7753 (delta 5882), reused 7715 (delta 5844), pack-reused 0
Receiving objects: 100% (7753/7753), 1.07 MiB | 5.91 MiB/s, done.
Resolving deltas: 100% (5882/5882), done.
$ cd buildroot-external-microchip/
$ git checkout -b sama7d65 linux4microchip+sama7d65-2024.10
Switched to a new branch 'sama7d65'
$ cd ..

$ ls buildroot-external-microchip/
board Config.in configs COPYING
README.md system
docs
external.desc
external.mk
package
patches

$ ls -1 buildroot-external-microchip/configs/sama7d65*
configs/sama7d65_curiosity_graphics_defconfig
configs/sama7d65_curiosity_headless_defconfig

Build the rootfs image

To build the the rootfs image that we provide for sama7d65 curiosity, you will have to execute from the directory where you cloned the required repository:

$ cd buildroot-at91
$ BR2_EXTERNAL=../buildroot-external-microchip/ make sama7d65_curiosity_graphics_defconfig
$ make

Once compilation is done, have a look to output/images directory to see what has been generated:

$ ls -1 output/images/
at91bootstrap.bin
at91-sama7d65_curiosity.dtb
boot.bin
boot-plaintextimg.bin
boot.vfat
rootfs.ext2
rootfs.ext4
rootfs.tar
sama7d65_curiosity_at25ff321a_click1.dtbo
sama7d65_curiosity.itb
sama7d65_curiosity.its
sama7d65_curiosity_lvds.dtbo
sama7d65_curiosity_mipi.dtbo
sama7d65_curiosity_pwm.dtbo
sama7d65_curiosity_tcb_pwm.dtbo
sama7d65-sdcardboot-uboot-4.0.7.bin
sama7d65-sdcardboot-uboot-4.0.7-sama7d65-ea.bin
sama7d65-sdcardboot-uboot-4.0.7-sama7d65-ea-plaintextimg.bin
sdcard.img
u-boot.bin
uboot-env.bin
zImage

All software components are there: booloaders, kernel, device tree and rootfs. The SD Card image ready to be flashed: sdcard.img

: If you do a make clean, you will delete the rootfs but also the cross toolchain, redoing the whole process again will take time.

Recent FAQ

BuildRoot: • Sama 7 d 65 Curiosity Buildroot BSR: SAMA7D65 ready-made Buildroot images & BSR. (Sama7d65Curiosity)
• Using Systemd: Basic systemd user guide. (Sama7d65Curiosity, Sama5d29Curiosity, Sam9x75Curiosity, Sam9x60Curiosity, Sama7g5-ek, Sama5d2-icp, Sam9x60EK, Sama5d27WLSom1EK, Sama5d27Som1EK)
• Build Issue Buildroot G 1: Buildroot gst1-at91-gstreamer. (Sam9x75Curiosity, Sam9x60Curiosity, Sama7g5-ek, Sama5d2-icp, Sam9x60EK, Sama5d27WLSom1EK, Sama5d27Som1EK)
• Sam 9 x 60 Ek Attaching Tm 5000 Display: Addition to the other generic FAQ about LCD displays: ConnectModuleFromPDA. (Sam9x60EK)
• Build Issue Open Wrt Ubuntu 2004: OpenWrt build error on Ubuntu 20.04. (Sama5d2-icp, Sam9x60EK, Sama5d27WLSom1EK, Sama5d27Som1EK, Sama5d2Xplained)
• Audio FAQ: Audio with ALSA. ()

Buildroot

Introduction

Related Links

How to build Buildroot for AT91

Prerequisites

Get sources

Build the rootfs image

Cross toolchain

Customizing Buildroot

Customizing Busybox / Linux / U-boot / uClibc configuration

Adding/removing packages from the rootfs

Updating the rootfs for another nand flash device

Add your own software to Buildroot

How to build Buildroot for sama7d65

Prerequisites

Get sources

Build the rootfs image

Recent FAQ