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.
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).
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 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.
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-exceet). Please note, that the subdirectory yocto-exceet is created automatically.
git clone email@example.com: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
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:
- Running the
- Updating the core repository (yocto-exceet) 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
- Running the
- Initialize the 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 repositories.
All you have to know for initializing the correct build can be found in the following table:
|iMXceet UL-2 S||active||3.14||
|iMXceet UL-2 S 35||active||3.14||
|iMXceet UL-2 S 43||active||3.14||
|iMXceet UL-2 S 50||active||3.14||
|iMXceet Solo S||active||3.14||
|iMXceet Solo S 43||active||3.14||
|iMXceet Solo S 50||active||3.14||
|iMXceet Solo S 70||active||3.14||
|iMXceet Dual S 50||active||3.14||
|iMXceet Solo S 70||active||3.14||
|iMXceet Solo S 101||active||3.14||
|iMXceet Quad S||active||3.14||
To use a Kontron Electronics build with a certain machine:
. init-env -m <machine> build-exceet-morty
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 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
. 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.
image-exceet by default includes Qt5 and demo apps. If you want a leaner image you can try
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.
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
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 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 running
git checkout -- .or a similar command
- Stash your changes for later reuse, see: git stash
- Commit your changes and if necessary, push them to the remote. You might also want to update
Other Helpful Scripts
yocto-exceet/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-remoteinitializes 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
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.
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:
- The image recipe in
recipes-corefor image-specific settings
- The distro config in
conf/distrofor distro-specific settings
- The machine config in
conf/machinefor machine-specific settings
- 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
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):
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
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.
For more information about the mighty
devtool, please visit the Yocto Manual.
To start working on the
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:
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