Skip to content

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.

Installing Prerequisites

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

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.

cd ~

When using SSH access, add the Kontron Electronics GitLab server to the list of known SSH hosts on your machine by running:

ssh git@git.kontron-electronics.de

Clone the main repository (yocto-exceet). Please note, that the subdirectory yocto-exceet is created automatically.

git clone https://git.kontron-electronics.de/sw/yocto/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 build-ktn-imx or build-stm32mp.

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 the init-env script.

By default this script also runs the meta-update script (see Updating the repositories).

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:

  1. Running the meta-update script from yocto-ktn/scripts/

    1. Updating the core repository (yocto-ktn) to the latest revision
    2. Cloning/Updating the build-repository (only if -u option is used)
    3. Parsing the file conf/repo.conf in the build directory
    4. Cloning/Updating all meta layers to the revisions from repo.conf

  2. Running the oe-init-build-env script from layers/openembedded-core

    1. Initialize the build environment for Bitbake
    2. If no conf/local.conf file exists in the build-directory, create one from the template

  3. Selecting a machine if the -m option is used, by setting the environment variable MACHINE.

For other options of init-env and meta-update, please run . init-env -h or meta-update -h.

By sourcing init-env you also change to the build directory and therefore you are ready to run the bitbake command.

Examples

Here are some examples for intializing different kinds of builds.

cd ~/yocto-ktn

To Init the 'build-ktn-imx' for the 'kontron-mx6ul' Machine: 

. init-env -m kontron-mx6ul build-ktn-imx

Important

When building for the first time you additionally have to set the option -u

To use a custom build-<customer>: 

. 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 -s option: 

. 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 environment.

The 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 yocto-exceet/layers. The 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 init-env.

To update the current build without using init-env you can run meta-update directly: 

meta-update -u

If you only want to check out the meta-layers specified in repo.conf, maybe because you ran some manual git checkout commands in the layers and want to return to the state defined in repo.conf: 

meta-update

Important

Please note that whenever you run init-env or 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:

  1. Discard your uncomittet changes if you do not need them anymore by running git checkout -- . or a similar command or
  2. Stash your changes for later reuse, see: git stash or
  3. Commit your changes and if necessary, push them to the remote. You might also want to update repo.conf afterwards.

Other Helpful Scripts

The yocto-ktn/scripts directory contains some more scripts, you might find helpful:

  1. meta-bump updates your 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.

  2. meta-status prints information about the current state of the meta layers.

  3. init-remote2 initializes 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.