Setting up and using the build environment
This chapter explains the steps necessary to download (clone) a copy of the Yocto-based BSP for Kontron Electronics STM32MP Boards. 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.
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. You can skip the next chapter and go on with Initialize the build environment.
Installing prerequisites on linux PC
Ubuntu 16.04 LTS 64-bit is used as reference OS for the development PC. The newer Ubuntu 18.04 LTS 64-bit version should also work well and should be the preferred version for new installations.
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-get install sed wget curl cvs subversion git-core coreutils unzip texi2html texinfo docbook-utils gawk python-pysqlite2 diffstat help2man make gcc > sudo apt-get install build-essential g++ desktop-file-utils chrpath libxml2-utils xmlto docbook bsdmainutils iputils-ping cpio python-wand python-pycryptopp python-crypto > sudo apt-get install libsdl1.2-dev xterm corkscrew nfs-common nfs-kernel-server device-tree-compiler mercurial u-boot-tools libarchive-zip-perl bison flex > sudo apt-get install ncurses-dev bc linux-headers-generic gcc-multilib g++-multilib libncurses5-dev libncursesw5-dev lrzsz dos2unix lib32ncurses5 repo libssl-dev
On Ubuntu 18.04 CubeProgrammer requires the original OracleJava 8 JRE version to be installed. See Ubuntu Wiki page for installation instructions.
Installing Java 8 JRE the manual way without using the PPA works best.
Gaining access to the repositories
To gain access to the Kontron Electronics repositories please request a useraccount on the Kontron Electronics GitLab server. We recommend to use SSH and authentication with keys.
In the Kontron VMware image a standard user account is already integrated which can fetch all required sources from the GitLab server. So for the first steps you don't neet to request a user account when you use the VMware image.
Please note that if port 9418 is blocked in your environment, you are not able to use the git-protocol. As some of the openembedded recipes for Yocto rely on the git-protocol, you won't be able to use the Yocto system properly in this case (fetch-tasks may fail).
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
Go to the Kontron gitlab server at https://git.kontron-electronics.de
and log in. 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
ida_rsa.pub file from the previous step and paste it in the "Key" input field. Click
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.
As the Kontron Electronics GitLab server is not in the list of known SSH hosts on your machine initially, add it once by running:
Clone the main repository (yocto-ktn). Please note, that the subdirectory yocto-ktn 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 Demo-Kits are also kept in repositories like
build-stm32mp for the layer
meta-ktn-stm32mp for the board adaptions. Different Yocto community branches
can be fetched by choosing the appropriate branch (e.g. thud).
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.
Initialize the build environment
Before you are able to build anything for your board, you first have to fetch the yocto metadata which describes which components shall be used and how to build the software for your image.
The Kontron BSP distinguishes between the core-repository, build-repository and the meta-layers:
The core-repository is the directory
yocto-ktn which you have already cloned. It contains
scripts to fetch the yocto environments for your board.
The meta-layers are yocto layers placed in
yocto-ktn/layers subdirectory. Yocto finds there
all the recipes it needs to build the desired software and images.
The build repository is a directory named
customized boards). It contains the information what contains and how to create the yocto
environment for your board. The most important files in this directories are:
It contains information which meta-layers in which version should be fetched and placed in the
yocto-ktn/layerssubdirectory. This file is special to the Kontron BSPs and
is the yocto configuration file to configure which directories contain recipes to use
is the yocto configuration file for local build settings
After a yocto build, the build repository also contains the build results and indermediate files.
To initialize your build environment you have to source the
init-env script. By default this
script runs the
meta-update script (see Updating the repositories)
to fetch all yocto layers with the version configured in the
conf/repo.conf file. So this sets
up your yocto environment with its layers.
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 yocto build environment
- If no
conf/local.conffile exists in the build-directory, create one from the template
Setting a machine if the
-moption is used
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 a
There are numerous predefined build configurations available for Kontron Electronics demo and evaluation hardware. Depending on which Yocto community branch they are based on, they can be found in different branches (e.g. thud).
Often there is only one MACHINE for numerous STM32MP demo boards. In this case, different boards are supported by different device tree configurations in bootloader and linux kernel. When an image for this machine is built, all device trees are integrated in this image. So the same image can boot on all supported hardwares.
Which device configuration is chosen is determined by the setting of the 'HOUSING' variable in u-boot. The correct setting can be found in the hardware description for your Kontron board.
For example to initialize the build environment for a Kontron Demo-Kit type:
> cd ~/yocto-ktn > . init-env -r thud build-stm32mp
-r option you can choose the appropriate revision of this git checkout. The revision
can be a git branch (as used above) or a special git commit with its commit id or it can also be
a git tag like
When building for the first time you additionally have to set the option
If you have a full customized boards use your customized build repository
. init-env build-<customer>
To use a
build-customer with a specific Yocto BSP branch (only if multiple branches such as rokco,
thud, 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>
Now 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 building what you want.
Repository and directory Structure
This is how the directory tree will look after you cloned yocto-ktn, initialized your build environment and did an image build:
yocto-ktn # the main repository │ ├── build-stm32mp # a build repository (after initializing the build environment) │ │ │ ├── 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 (after building an image) │ ├── deploy │ │ ├─ images # contains image files and binaries for the target │ │ ├─ deb # 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 (after initializing the build environment) │ │ # (each one is a git repository) │ │ │ ├ meta-openembedded # contains basic meta layers │ ├ meta-st # contains all specific stuff to support the STM32MP SOC and the OpenST Linux distribution │ ├ meta-ktn # contains all Kontron adaptions and modifications for all Yocto based boards │ ├ meta-ktn-stm32mp # contains all Kontron adaptions specific to the STM32MP SOC │ └ ... │ ├── 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
Updating the Repositories
As time goes by new versions of the used layers may be available. For this you can use the
meta-update utility. Updating the repositories is conveniently done by running the
yocto-ktn/scripts. However this is often not necessary, because it is automatically run
while initializing the build environment.
meta-update script tries to fetch the most recent versions of the core repository
(yocto-ktn) and the (customer) build repository (only if option
-u is set) from the server and
then parses the
repo.conf file in the build repository.
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
repo.conf, maybe because you ran some
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 running
git checkout -- .or a similar command
- Stash your changes for later reuse, see:
- 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 helpful:
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.