There are many embedded Linux distributions ready for use with good functionality, but at the cost of image size, some images can reach 4GB. Sometimes we want embedded systems that support Linux with only the minimum packages needed for our system, such as running a small FTP server with no graphical interface.
To fulfill the object of getting a custom image, we can automate and facilitate building a distro through some build tools for embedded Linux-based systems. Some existing ones today include Yocto and Buildroot, which are open source projects.
Buildroot is a tool for automating the creation of Embedded Linux distributions. It builds the code for the architecture of the board so it was set up, all through an overview of Makefiles. In addition to being open-source, it is licensed under GPL-2.0-or-later.
How to Install
Before starting Buildroot installation, let’s assume you have a Linux environment ready for building C projects, as well as tools for git, svn, and rsync.
You can get more information about the requirements through the official Buildroot documentation.
In order to install Buildroot, we will clone the repository through Github:
Analyzing the Buildroot
Once inside the Buildroot directory, we will have the following tree:
Each directory holds a set of files needed to set up a part of the build. Here we can highlight:
- board: Contains files for target board mapping and configuration, such as flash memory address and device tree files;
- configs: Contains a series of pre-set configurations to automate which packages and properties should be added to the embedded image;
- packages: Contains all official packages available so far for Buildroot. We are not limited to these packages only, Buildroot allows we to create new custom packages.
We will give more focus to package folder, as our main interest will be to customize the packages installed in our image.
As an example, let’s look at the fmt package, which consists of 3 files:
Config.in is the package description to be used for Buildroot configuration, it is responsible for maintaining the information for the user interface when choosing which packages to build. It also contains the package dependencies.
The fmt.mk file is the Makefile recipe for setting up, building, and installing the library.
This file stores default properties for all other packages, such as its version, site from which to download the source code, software license name, and where to find that license file.
Here you can see that at the end a module called cmake-package is invoked. This module is responsible for handling projects using CMake, where it will execute all necessary commands, from configuration to installation of artifacts. This modularization allows for a higher level of automation, otherwise it would be necessary to describe all CMake commands for each package.
The last and not the least file, fmt.hash holds the checksum of the downloaded file directly from the site.
Although we are using SHA-256, Buildroot is able to support other formats like SHA-1 and MD5. The checksum is automatically verified by Buildroot during package download. If the value found is not the same as described, an error will be raised.
Configuring the Custom Image
As our target platform is RaspberryPi3, Buildroot offers a pre-configured file for this board, which is located within the configs directory.
To ask Buildroot that we want to build our configuration from RaspberryPi3, we should use the following command:
Once executed, this command will generate the file .config, which contains all the packages, kernel, toolchain and properties needed for our image. To add new packages or edit existing ones, we need to manipulate this file, but this is not very automated and can result in a number of errors during the construction. That’s why Buildroot has more user-friendly interfaces, where you can customize your final configuration, and automatically resolve dependencies. There are different formats for this interface you can try some of them:
During this example we will use menuconfig, as it has a minimal graphical interface and does not require other system dependencies like Qt.
After executing the configuration command, we will have the following output:
As we had already detailed the fmt library before, we will include it in our image, so we have to navigate thought the menu in the following way:
Target Packages -> Libraries -> Text and terminal handling -> fmt
To get more information about the package, you can enter ?. It will show the same content as we had seen in the Config.in file. Once selected, we can save the current setting through the panel and exit by pressing ESC.
Building the Image
Once setup is ready, we can proceed to the longest step in this tutorial, building the image. Although the build is just a command, Buildroot will have to download all the sources that are present in the configuration file, build from sources and finally generate a custom image. To start the build process just run:
From now, Buildroot will take care of the entire build process, which may take a few hours the first time. For future builds, the cache may be reused which will down the build time to a few minutes.
Using Conan for Buildroot builds
Although Buildroot can accept new packages through its package structure, the build process is still a bit long, it could take few hours on the first time. But what if this process could be reduced to just a few minutes by downloading pre-built packages? Let us see some features and aspects from Conan which are related to our scenario:
- Able to provide a unified view of all binaries for all platforms and configurations, not only buildroot;
- Developers might develop fast, test locally with native binaries in their Linux boxes;
- Faster builds, thanks to reusing binaries, not only for development but for production and releases;
- Best DevOps practices, avoiding rebuilding binaries from sources more than once.
Before introducing Conan into Buildroot, we need to understand how the structure of scripts that collaborate with buildroot for package building:
This list of Makefiles are responsible for executing the build process for each given package. Returning to the recipe example for the ZLib library, we have the following section:
This line tells us that the
pkg-cmake.mk script will be used to build the ZLib project. In the case of integrating Conan we will have to build a new script with the commands responsible for downloading the desired packages, according to the configuration given by Buildroot, and copy the artifacts to their proper locations.
Integrating Conan with Buildroot
Let’s create a new file called pkg-conan.mk in the
package/ directory. At the same time, we need to add it in
package/Makefile.in file in order to Buildroot be able to list it.
For script development we will break it down into a few steps. Because it is a large file, we will only portray parts of it in this post, but the full version can be found here.
Buildroot defines its settings, including processor, compiler version, and build type through variables. However, these variables do not have directly valid values for Conan, so we need to parse most of them. Let’s start with the compiler version, by default Buildroot uses a GCC-based toolchain, so we will only filter on its possible versions:
This same process should be repeated for build_type, arch, and so on. For the Conan package installation step we will have the following routine:
The Conan install command will be executed as usual, but the settings and options are configured through what was previously collected from Buildroot, and accept new ones through the Buildroot package recipe. Because it was a scenario where previously all sources were compiled in the first moment, we will set Conan build policy to
missing, so any package will be built if not available.
Also, note that we are using the generator
deploy, as we will need to copy all the artifacts into the Buildroot internal structure. Once built, we will copy the libraries, executables and headers through the following routine:
With this script we will be able to install the vast majority of Conan packages, using only simpler information for each Buildroot recipe.
Installing Conan Zlib
Once we have our script for installing Conan packages, now let’s install a fairly simple and well-known project: zlib. For this we will create a new recipe in the package directory. Let’s start with the package configuration file:
The contents of the file Config.in should be as follows:
Now let’s go to the conan-zlib.mk that contains the Zlib data:
An important note here is the fact that
CONAN_ZLIB_SITE is required even if not used for our purpose. If it is not present, Buildroot will raise an error during its execution. The other variables are simple, just expressing the package reference, name, version and license. Note that in the end we are calling our script which should execute Conan.
Once created, we still need to add it to the Buildroot configuration list. To do so, let’s update the list with a new menu named
Conan. In package/Config.in file, let’s add the following section:
Now just select the package through menuconfig:
Target Packages -> Conan -> conan-zlib
Once configured and saved, simply run
make again to install the package. During its installation we will have the following output:
As you can see, Conan is following the same profile used by Buildroot, which gives us the advantage of not having to create a profile manually.
At the end of the installation it will be copied to the output directory.
Customizing Conan remote
Let’s say we have an Artifactory instance where all packages are available for download. How could we customize the remote used by Buildroot? We need to introduce a new option, where we can write the remote name and Conan will be able to consume such variable. First we need to create a new configuration file to insert new options in Conan’s menu:
The file Config.in should contain:
Also, we need to parse the option
CONAN_REMOTE_NAME in pkg-conan.mk and add it to Conan command line:
Now we are ready to set our specific remote name. We only need to run
make menuconfig and follow the path:
Target Packages -> Libraries -> Conan -> Conan remote name
And we will see:
Now Conan is configured to search for packages in the remote named artifactory. But we need to run
Note that it will cost less time to build, since now we have the cache provided by Buildroot. Now we are ready for the last step.
Installing the Image
After two hours and a few coffees and if no errors have occurred during the process we will have the following output:
These artifacts are the final compilation of everything that was generated during the build process, here we will be interested in the sdcard.img file. This is the final image that we will use on our RaspberryPi3 and it is only 153MB. Compared to other embedded distributions like Raspbian, it is much smaller.
Now let’s copy the image to the destination SD card:
Remember that the mounting point of your SD card may vary depending on your distribution.
Once done, plug the SD Card into the RaspberryPi3 and power the card, already connected to a video output. You will see the bootloader running normally and finally you will be presented to login screen where the default user is root, no password needed.
In this post we talked about how to use Buildroot to create a Linux distribution without much effort and resulting in a very lean image.
Buildroot helps automate the process of creating a custom embedded Linux distribution with only the developer packages of interest.
Although the build process may take a few hours, with Conan integrating and replacing a few packages, this time can be reduced to just a few minutes.
Interested in knowing more or commenting on the subject? Please do not hesitate to open a new issue.