Setting up and Using the Build System

This chapter explains the steps necessary to download (clone) a copy of the Yocto-based BSP for Kontron Electronics i.MX6 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.

Ubuntu 16.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

Please also see the official Yocto docs for additional packages, that might be needed.

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.

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

Using SSH

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-exceet                # the main repository
│
├── build-exceet-morty      # 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-exceet           # contains all Kontron 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-exceet)

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 ~

As the Kontron Electronics GitLab server is not in the list of known SSH hosts on your machine initially, add it once 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 git@git.kontron-electronics.de:yocto-exceet/yocto-exceet.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-exceet system. Customer-specific build configurations are also kept in a separate build directory. The default build configurations for Kontron Electronics demoboards are also kept in repositories like build-exceet-morty or build-exceet-rocko.

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.

Building an Image

Initializing the build environment

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

Sourcing the init-env script automates the following tasks:

  1. Running the meta-update script from yocto-exceet/scripts/
    1. Updating the core repository (yocto-exceet) 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/poky/
    1. Initialize the build environment
    2. If no conf/local.conf file exists in the build-directory, create one from the template
  3. Setting a machine if the -m option is used

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 a bitbake.

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

All you have to know for initializing the correct build can be found in the following table:

Hardware Status Kernel init-env command
iMXceet UL-2 S active 3.14 . init-env -m imxceet-ul-2-s build-exceet-morty
iMXceet UL-2 S 35 active 3.14 . init-env -m imxceet-ul-2-s-35 build-exceet-morty
iMXceet UL-2 S 43 active 3.14 . init-env -m imxceet-ul-2-s-43 build-exceet-morty
iMXceet UL-2 S 50 active 3.14 . init-env -m imxceet-ul-2-s-50 build-exceet-morty
iMXceet Solo S active 3.14 . init-env -m imxceet-solo-s build-exceet-morty
iMXceet Solo S 43 active 3.14 . init-env -m imxceet-solo-s-43 build-exceet-morty
iMXceet Solo S 50 active 3.14 . init-env -m imxceet-solo-s-50 build-exceet-morty
iMXceet Solo S 70 active 3.14 . init-env -m imxceet-solo-s-70 build-exceet-morty
iMXceet Dual S 50 active 3.14 . init-env -m imxceet-dual-s-50 build-exceet-morty
iMXceet Solo S 70 active 3.14 . init-env -m imxceet-dual-s-70 build-exceet-morty
iMXceet Solo S 101 active 3.14 . init-env -m imxceet-dual-s-101 build-exceet-morty
iMXceet Quad S active 3.14 . init-env -m imxceet-quad-s build-exceet-morty
cd ~/yocto-exceet

To use a Kontron Electronics build with a certain machine:

. init-env -m <machine> build-exceet-morty

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 jethro, morty, 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>

Bitbake an Image

To build a single package, an image for the target or a toolchain, Yocto uses the bitbake command. To build a complete image for the Kontron hardware, you can run the following command. Please note, that building from scratch can take a long time and needs a lot of disk space and RAM.

bitbake image-exceet

Building image-exceet by default includes Qt5 and demo apps. If you want a leaner image you can try image-exceet-minimal.

bitbake image-exceet-minimal

Updating the Repositories

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-exceet) 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-exceet/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-remote 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.

Modifying the BSP

Modifications

If you make any modifications to the BSP yourself and you want to use these changes in your final product, please stay in touch with the Kontron developers and push those changes back on the Kontron server, so the Kontron Linux team knows what you are doing.
This way it is much easier for the Kontron developers to help you if you are stuck.

Local or temporary modifications

On the first initialization a local.conf file is created in the conf directory of your build. This file is usually not tracked by git and is meant to be used only for local or temporary changes. Please check local.conf and read the comments in the file to find out about some default options.

Warning

If you have changes in your local.conf that should not stay local, but need to be set as default for everyone who uses the build, then find a way to move these changes to the correct file. Some popular places in the meta layers are:

  1. The image recipe in recipes-core for image-specific settings
  2. The distro config in conf/distro for distro-specific settings
  3. The machine config in conf/machine for machine-specific settings
  4. Recipe of some package for package-specific settings

Modifying the Kernel Configuration

The kernel configuration can be modified using the following steps:

Make modifications and save them

bitbake virtual/kernel -c menuconfig

The file
tmp/work/<machine>-exceet-linux-gnueabi/linux-imx-exceet/3.14.38-r0/build/.config will be created

Rebuild the kernel for testing

bitbake virtual/kernel -C compile -f

Test your changes

Create reduced defconfig

bitbake virtual/kernel -c savedefconfig

Copy defconfig from build directory to your customer layer (meta-customer):
from

cp ~/yocto-exceet/build-exceet-morty/tmp/work/<machine>-exceet-linux-gnueabi/linux-imx-exceet/3.14.38-r0/build/defconfig ~/yocto-exceet/layers/meta-<customer>/recipes-kernel/linux/linux-imx-exceet/mx6/defconfig

Rebuild kernel

bitbake virtual/kernel

Using devtool to work on source code

To work on the source code of any package it is most convenient to use the devtool utility. As an example we will show how to modify the kernel code.

Tip

For more information about the mighty devtool, please visit the Yocto Manual.

To start working on the linux-imx-exceet code:

devtool modify linux-imx-exceet

A separate workspace layer will be created and the kernel source tree will be extracted there. Do your code changes and run a build with:

bitbake linux-imx-exceet

Test your changes and create patches if necessary. To reset to the previous state and build without the changes in the workspace run:

devtool reset linux-imx-exceet