Yocto Build System
This chapter explains the steps necessary to setup and use the Yocto-based build system in order to generate BSP images for Kontron hardware. After setting up the system you can start a build and get a bootloader, kernel image and root filesystem to run on your target hardware.
This is a generic guide, that only describes the basic setup. For practical examples and more details for your platform of choice, please see the platform-specific guides:
Please note that Kontron Electronics might also provide you with a pre-configured virtual machine image. If you use this, the build system is already installed and you can immediately start to build an image for your target device.
Ubuntu 18.04 LTS 64-bit is used as reference OS for the development PC.
If you start from the beginning, it might be necessary to install some prerequisites on your development PC. Therefore do
sudo apt update
to update your package index. Afterwards start the package manager apt to install the required packages:
sudo apt install git-core gcc g++ python gawk chrpath texinfo libsdl1.2-dev \ gdb-multiarch gcc-multilib g++-multilib
Please also see the official Yocto docs for additional packages, that might be needed.
GitLab Server and Repositories
For an overall overview of the server and the available reposiories, please consult the "Git Server Overview" page.
Gaining Access to Private Repositories on the KED GitLab Server
Skip if you only intend to use public repositories
All the repositories that are not customer- or project-specific are publicly accessible. Therefore to get started with an Eval-Kit or generic Kontron hardware, you can skip this step
Generating a SSH-key on your Machine
First check if you already have an existing SSH-key in
~/.ssh/ (id_rsa and
id_rsa.pub). If yes you can use it in the next step. If not use the following
commands to generate a key:
mkdir ~/.ssh chmod 700 ~/.ssh ssh-keygen -t rsa
You can add a passphrase for additional security when prompted. For more information on SSH authentication please visit the Ubuntu Help.
Adding the SSH-key to your GitLab Account
In the top right corner click on your profile picture. Click "Settings" and
navigate to "SSH Keys" in the left navigation. Copy and paste your key and give
it a name (e.g. work-pc). Copy the content of your
ida_rsa.pub file from the
previous step and paste it in the "Key" input field. Click "Add Key".
Repository and Directory Structure
This is how the directory tree with the most important files and directories will look like:
yocto-ktn # the core repository │ ├── build-foo # a build repository │ │ │ ├── conf │ │ ├── repo.conf # specifies the revisions of all layers │ │ ├── local.conf # specifies local settings for the build │ │ └── bblayers.conf # specifies all layers that will be parsed by bitbake │ │ │ └── tmp # contains all of the build data │ ├── deploy │ │ ├─ images # contains image files and binaries for the target │ │ ├─ ipk # contains packages │ │ ├─ licenses # contains licenses of the packages in use │ │ └─ sdk # contains SDK and toolchain binaries │ │ │ └── work │ └─ ... # contains all source and build files for the packages │ ├── layers # contains all meta layers with recipes │ │ # (each one is a git repository) │ │ │ ├ poky # contains the Yocto/Poky build system and meta data │ ├ meta-openembedded # contains basic meta layers │ ├ meta-ktn # contains basic Kontron adaptations and modifications | ├ meta-ktn-xyz # contains Kontron platform adaptations and modifications │ └ ... │ ├── scripts # contains scripts to automate certain tasks ├── downloads # contains all the files downloaded by the fetcher │ # (shared by all builds) ├── sstate-cache # contains the sstate cache (shared by all builds) └── init-env # this is a script to initialize the build environment
Cloning the Core repository (yocto-ktn)
To clone the necessary repositories for your build, go to a directory on your system where you want all the data needed (including source files, build, cache, config, etc.) to be saved (usually $HOME). Please note, that - depending on your build - this usually requires a lot of disk space (> 50 GB). If you have to choose between a SSD and a HDD for running the build, use the SSD as this gives you a little extra speed.
When using SSH access, add the Kontron Electronics GitLab server to the list of known SSH hosts on your machine by running:
Clone the main repository (yocto-exceet). Please note, that the subdirectory yocto-exceet is created automatically.
git clone https://git.kontron-electronics.de/yocto-ktn/yocto-ktn.git
Cloning Additional Build Repositories
Customer-specific data like kernel configurations, devicetrees for custom
boards, custom recipes, etc. is kept in a separate meta-layer within the
yocto-ktn system. Customer-specific build configurations are also kept in a
separate build directory. The default build configurations for Kontron
Electronics Eval-Kits and standard hardware are also kept in repositories like
The most convenient way to initialize a build and clone all necessary repositories is by using the init-env script. Run this script with the desired build configuration (name of the build repo) as argument. See Initializing the build environment.
Initializing the Build Environment
Before being able to build an image, the metadata for all components needs to be
fetched. This is usually done through initializing the environment by sourcing
By default this script also runs the
meta-update script (see Updating the
Metadata and Repository Overview
For an overview of the repositories and a summary of the metadata inside them, please have a look at the "Git Server Overview" page.
Sourcing the init-env script automates the following tasks:
- Updating the core repository (yocto-ktn) to the latest revision
- Cloning/Updating the build-repository (only if
-uoption is used)
- Parsing the file
conf/repo.confin the build directory
- Cloning/Updating all meta layers to the revisions from
- Initialize the build environment for
- If no
conf/local.conffile exists in the build-directory, create one from the template
- Initialize the build environment for
Selecting a machine if the
-moption is used, by setting the environment variable
For other options of init-env and meta-update, please run
. init-env -h or
init-env you also change to the build directory and therefore you
are ready to run the
Here are some examples for intializing different kinds of builds.
To Init the 'build-ktn-imx' for the 'kontron-mx6ul' Machine:
. init-env -m kontron-mx6ul build-ktn-imx
When building for the first time you additionally have to set the option
To use a custom
. init-env build-<customer>
To use a custom
build-<customer> with a specific Yocto BSP branch (only if
multiple branches such as thud, warrior, etc. are available):
. init-env -r <BSP branch> build-<customer>
To initialize the environment and update to the latest revision of the build
repository, use the
-u (update) option:
. init-env -u build-<customer>
To initialize the environment and skip checkout errors (e.g. when you have local
uncommited changes in some layer), use the
. init-env -s build-<customer>
After initializing, you are ready to build a recipe, a complete image or the sdk
for your machine with the Yocto
Bitbake tool. See Using
Bitbake for further information.
Updating the Repositories
As time goes by new versions of the used layers may be available. Updating the
repositories is conveniently done by running the
meta-update script in
yocto-exceet/scripts. However this is often not necessary, because it is
automatically run while initializing the build
meta-update script tries to fetch the most recent versions of the core
repository (yocto-ktn) and the (customer) build repository (only if option
is set) from the server and then parses the
repo.conf file in the build
The meta-layers with the specified revisions are then checked out to
meta-update script needs to know the current build,
but you usually don't need to set the
-b option as the script gets the current
build from an environment variable
BUILDDDIR, that is set while running
To update the current build without using init-env you can run
If you only want to check out the meta-layers specified in
because you ran some manual
git checkout commands in the layers and want to
return to the state defined in
Please note that whenever you run
meta-update and have local
changes in one of the repositories, you can run into problems while the
script tries to checkout a certain revision of the build repository or a
meta layer. To resolve these problems, go to the repository and do one of
the following steps, depending on your situation:
- Discard your uncomittet changes if you do not need them anymore by
git checkout -- .or a similar command or
- Stash your changes for later reuse, see: git stash or
- Commit your changes and if necessary, push them to the remote. You might
also want to update
Other Helpful Scripts
yocto-ktn/scripts directory contains some more scripts, you might find
repo.conf. You can set a certain layer to a specific revision, or you can update all layers to the latest revision by running the script without any arguments.
meta-statusprints information about the current state of the meta layers.
init-remote2initializes TFTP, NFS and a webserver on your local machine to use network boot on your target device and to be able to install packages on your target from a local pacakge server. It also can get its configuration from a file. For examples see the 'init-remote_*' files in 'conf' subdirectory your build directory.