simplest-yocto-setup
is an example of the simplest, but realistic and
working, Yocto/OpenEmbedded setup.
It aims at providing an example of how Yocto/OE can be used as the embedded Linux build system for end products without unnecessary complications.
While working for several Bootlin customers on their Yocto/OpenEmbedded setups we have seen many problems caused by unnecessary complications in their layers.
We have spent a lot of time in educating to writing clean layers, which often involved fixing problems by removing a lot of the code they had written or they had taken from existing third-party layers. In other words: making the code simple and "stupid", resulting in a more understandable, more efficient, easier to upgrade and less buggy build environment.
This repository is implementing a similar setup, aiming at being a reference for product companies in need to set up a Yocto/OpenEmbedded build environment or to clean up what they already have.
This repository is composed of:
.config.yaml
: a kas configuration filemeta-kiss
: the layer with the (fictitious) metadata for the products
of a (fictitious) companyThe .config.yaml
is the configuration file for the
kas utility, which allows to easily download
all the required third-party components in the correct place and enable
them in the configuration. In this example it downloads and enables:
bitbake
build engineopenembedded-core
repository which contains the meta
layer
with all the "core" recipesmeta-arm
repository which contains the meta-arm
and
meta-arm-toolchain
layersmeta-kiss
layer, not downloaded as it is already part of this
repository, but enabled in build/conf/bblayers.conf
Using kas is not mandatory to use Yocto/OpenEmbedded, but we found it simple and convenient. You can use another tool for your project if so you prefer.
meta-kiss
layermeta-kiss
is a layer that demonstrates how a realistic layer for a
product company can (and, in our opinion, should) look like.
It is named after the KISS principle which "states that most systems work best if they are kept simple rather than made complicated" (source: Wikipedia).
Here we used "kiss" as the hypothetical name of a fictitious company. The
machine configurations in meta-kiss implement fictitious products, but
except for their name they are actual development boards and the output
images can be used on these boards. In real world use cases a layer
implementing company products can reasonably be called
meta-<company-name>
and the machine names should be named after the
product names.
The meta-kiss
layer provides:
Note that meta-kiss
is a single layer. The bitbake
Yocto/OE build
engine is powerful enough to handle lots of machines, recipes and even
multiple distros in a single layer. Thus using a simple layer in your
company is perfectly fine and encouraged, unless your need are so complex
that splitting it into multiple layers proves useful.
The meta-kiss layer contains two machine configurations, called dogbonedark and stompduck.
The dogbonedark machine describes a fictitious product which in reality implements the BeagleBone® Black. In order to implement it we took the relevant content from the BeagleBone machine configuration found in the meta-ti-bsp layer.
We could of course have used the meta-ti-bsp layer directly, however since the hardware is very well supported by the mainline kernel and U-Boot we only needed to write (or copy and paste!) only a small amount of code.
Several BSP layers provided by hardware vendors bring in extra complexity, deviation from standard coding practices and even bugs and unnecessarily complex code. In the spirit of this project, we chose to provide an example of how you can do without them in many cases.
The stompduck machine describes a fictitious product which in reality implements the STM32MP157A-DK1. For the same motivations, the minimum necessary code in this case was taken from the STM32MP1 machine configuration found in the meta-st-stm32mp layer.
In addition to the steps needed to implement the dogbonedark
, for the
stompduck
machine we additionally chose to boot it using
TrustedFirmware-A (TF-A).
In order to build TF-A, using the existing
recipe
from the meta-arm layer looked like a good choice given the balance between
the code quality of the meta-arm layer itself and the complexity required
for a recipe to build TF-A. So we added this layer to the kas configuration
file together with the meta-arm-toolchain layer it depends on.
According to the kas configuration file, after cloning this repository the
dogbonedark
board is configured by default. Here's how you can have a
working image for that board in a few steps:
# If you don't have kas yet (needed once only):
pip install kas
# Use kas to download the third-party repositories needed
# (required the first time, or after changes to .config.yaml)
kas checkout
# Initialize the build environment
. openembedded-core/oe-init-build-env
# Run your first build
bitbake kiss-image
# Have dinner
# Find the output images here
ls -l tmp-glibc/deploy/images/dogbonedark/
# Flash the image (use your uSD card device instead of XYZ!):
sudo bmaptool copy tmp-glibc/deploy/images/dogbonedark/kiss-image-dogbonedark.wic /dev/XYZ
To use a different machine you can set MACHINE ?= "stompduck"
is
conf/site.conf
or in your shell environment and replace the machine name
in the paths.
That's all! Have a look around the code to know about the implementation details. We wrote some explanatory comments here and there which should help you understand the reason of several choices we made.
We also added some explanations in the git commit messages when the changes being committed were possibly not obvious. Look at the git history to discover the various steps we took, for example how we created the new meta-kiss layer skeleton initially and the process we took to add and modify a kernel defconfig.
In the end we hope you like the advantages of this clean setup: