Getting started with the Yocto Project
Now we show you how to create an image for your device. Note the process has many steps, but all of them are well defined and simple. The Yocto Project allows the user to change many settings and check the logs of build, among other things, but it isn’t the scope of this article. In the end, we’ll give some links that might help you.
Before starting, let’s see some definitions used in this area that will help you:
Cross-compilation is the action compile codes in a machine with a different architecture from the device’s architecture where these codes will run.
Host is the machine in which the code will be compiled. For example, the device in which the Yocto Project or other software is installed and set.
Target is the machine in which the binaries is generated in the host will run.
Layer is a set of recipes that have similarities or add features or capacities. An example is the meta-updatehub. This layer adds support to the UpdateHub, a solution to remote device updates.
Step 1: How do I begin?
Before cloning the Poky, check if you have all the packages needed to run the command below:
Install the poky with:
git clone git://git.yoctoproject.org/poky -b hardknott
Now initialize the environment running:
source poky/oe-init-build-env build
Running that command, you’ll be in the /build layer. Here also stay the conf/local.conf and conf/bblayers.conf, both essential to set image changes. We’ll speak about them ahead.
The Yocto Project receives updates every 6 months. So, if you want to stay up to date, check the actual version in Releases on the Yocto Project site. At the moment that this article was written, the last branch is Hardknott.
Recently the Yocto Project receive the first LTS version, the Dunfell. So if you doubt choose one version, you should prefer it.
Now, you must choose the device in which you want to generate the image. Below we put the links to some board support, but there are more options available online.
So, now you type the command below to set up the building environment:
MACHINE= “<machine>” source poky/oe-init-build-env
Example:
Let’s suppose that we want to generate an image to RaspberryPi 3, so we’ll run the code below:
MACHINE="raspberrypi3" source poky/oe-init-build-env
Step 2: Download and set the layers
The next step is to define features to add. The inclusion of features happens through recipes because many codes are already available there. That avoids reworking. To better organize the search, the recipes are grouped in layers. So, what you have to do is search for recipes you want, download this layer, and add in build/conf/bblayers.conf.
It’s possible to move the recipes to another layer. But just do that if you are sure you keep it updated and supported.
Depending on the feature, don’t forget to check if your board has the hardware necessary for this feature before adding any layer.
Step 3: Setting the local.conf
The local.conf is the main file to set features and define other info applied in the image during the build.
By default, the local.conf file in the Poky is extensive and brings all information about settings and options. To better illustrate the main variables, let’s erase the commented lines and some non-essential settings, leaving the file like below:
Now, let’s highlight some crucial variables that you must take care of:
MACHINE informs the target machine, which can be an emulated machine using QEMU or a hardware board. The machine can be defined as running the command to launch the built environment or manually in this file.
SDKMACHINE informs the target architecture.
DISTRO defines the build configuration policy. Initially, the default value will work for you. According to more features are added, and settings changed has, altering the DISTRO can be a good idea but don’t forget: to do this, you need to make sure of the new settings.
PACKAGE_CLASSES indicates that the packaging format will be used to generate the root filesystem. By default, this is set with package_rpm; others options are package_deb and package_ipk.
EXTRA_IMAGE_FEATURES allows the addition of extra packages in the image. Before adding a feature, check if the required package isn’t already included in the image will be generated.
BB_DISKMON_DIRS makes the monitoring of the disk space during the building process. As the Poky cooking the image much space can be used, so this setting allows you to define the limits to avoid errors.
CONF_VERSION is used to manage versions. It’s helpful to indicate breaking changes in the configuration schema.
PLATFORM_ROOT_DIR shows the path of the root folder.
A tip we give you is the case where you stay using a physics board, add serial communication in the local.conf. To enable this setting, just add ENABLE_UART = “1” in the local.conf and ready.
Step 4: Cook time!
If all is ok, you are ready to run the Bitbake command to generate the image:
bitbake <image choice>
The core-image-minimal and core-image-base are good options to test the image generation. Both are base-image, the first is littler and the second is composed of a good set of features.
Example:
bitbake core-image-minimal
To see other available image options click here.
This process takes time and depends on the network band to download the codes and processor to run the task of the bitbake.
A tip: take a new coffee!
Step 5: Burn it!
Finally, the image is ready to burn on the card. Go to the repo in which the image is build/tmp/deploy/images/<machine>/ and search the file.
There are many ways to do that, among them the dd command:
sudo dd if=image.extension of=/dev/sdX
Now just put the card in the device.
In case you want to see the layers available, you may check here.
The steps covered here are basics but are far from covering all the Yocto Project potential. The tool allows users to change, debug, test, run or emulate images with total support, besides counting on community help.
Do you want more? Some time ago, we published the article Update devices remotely with this Open Source tool on opensource.com. It’s a guide on how to use and integrate the UpdateHub from beginning to end. The tutorial shows how to add a feature in an image for RaspberryPi 3, using UpdateHub as an example!
Houston, we are ready!
Now, you have in your hand a custom-made image to your device with all features you want without storing the unnecessary code.
