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 libssl-dev
Please also see the official Yocto docs for additional packages, that might be needed.
Gaining Access to customer Repositories
The default repositories to build BSPs for demo and evaluation hardware are public and require no authentication. Customer-specific repositories might be private and need an user account on the GitLab server. To gain access to such 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 might 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 (only needed to access private repositories)
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 main repository
│
├── build-ktn # 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 generic Kontron configuration (distro, images, etc.)
│ ├ meta-ktn-imx # contains support for Kontron Electronics i.MX hardware
│ └ ...
│
├── 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-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 demoboards are also kept in repositories like build-ktn-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:
- Running the
meta-update
script fromyocto-ktn/scripts/
- Updating the core repository (yocto-ktn) to the latest revision
- Cloning/Updating the build-repository (update only if
-u
option is used) - Parsing the file
conf/repo.conf
in the build directory - Cloning/Updating all meta layers to the revisions from
repo.conf
- Running the
oe-init-build-env
script fromlayers/poky/
- Initialize the build environment
- If no
conf/local.conf
file exists in the build-directory, create one from the template
- 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 | 4.14 | . init-env -m imxceet-ul-2-s build-ktn-rocko |
iMXceet UL-2 S 43 | active | 4.14 | . init-env -m imxceet-ul-2-s-43 build-ktn-rocko |
iMXceet UL-2 S 50 | active | 4.14 | . init-env -m imxceet-ul-2-s-50 build-ktn-rocko |
iMXceet UL-2 S 70 | active | 4.14 | . init-env -m imxceet-ul-2-s-70 build-ktn-rocko |
KBox A-330 MX6 ULL | active | 4.14 | . init-env -m imxceet-ull-s-512 build-ktn-rocko |
iMXceet ULL S 50 | active | 4.14 | . init-env -m imxceet-ull-s-512-50 build-ktn-rocko |
iMXceet Solo S | active | 3.14 (4.14*) | . init-env -m imxceet-solo-s build-ktn-rocko |
iMXceet Solo S 43 | active | 3.14 (4.14*) | . init-env -m imxceet-solo-s-43 build-ktn-rocko |
iMXceet Solo S 50 | active | 3.14 (4.14*) | . init-env -m imxceet-solo-s-50 build-ktn-rocko |
iMXceet Solo S 70 | active | 3.14 (4.14*) | . init-env -m imxceet-solo-s-70 build-ktn-rocko |
iMXceet Dual S 50 | active | 3.14 (4.14*) | . init-env -m imxceet-dual-s-50 build-ktn-rocko |
iMXceet Dual S 70 | active | 3.14 (4.14*) | . init-env -m imxceet-dual-s-70 build-ktn-rocko |
iMXceet Dual S 101 | active | 3.14 (4.14*) | . init-env -m imxceet-dual-s-101 build-ktn-rocko |
KBox A-330 MX6 Dual | active | 3.14 (4.14*) | . init-env -m imxceet-dual-s build-ktn-rocko |
* Kernel for i.MX6 Solo/Dual/Quad
For boards based on i.MX6 Solo/Dual/Quad there are currently restrictions when using the 4.14 upstream Kernel (Video, Audio, etc.). Therefore the downstream NXP Kernel 3.14 with Kontron modifications is used by default.
cd ~/yocto-ktn
To use a Kontron Electronics build with a certain machine:
. init-env -m <machine> build-ktn-rocko
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 utilities for debugging, package-manager and SSH access. If you want a leaner image you can try image-exceet-minimal
, that has no SSH or package-manager.
bitbake image-exceet-minimal
For a full image including Qt5 and demo applications you can build image-exceet-qt
.
bitbake image-exceet-qt
Updating the Repositories
Updating the repositories is conveniently done by running the meta-update
script in yocto-ktn/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-ktn/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:
- Discard your uncomittet changes if you do not need them anymore by running
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
repo.conf
afterwards.
Other Helpful Scripts
The yocto-ktn/scripts
directory contains some more scripts, you might find helpful:
meta-bump
updates yourrepo.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-status
prints information about the current state of the meta layersinit-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:
- The image recipe in
recipes-core
for image-specific settings - The distro config in
conf/distro
for distro-specific settings - The machine config in
conf/machine
for 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
The file
tmp/work/<machine>-exceet-linux-gnueabi/linux-stable/4.14-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-ktn/build-ktn-rocko/tmp/work/<machine>-exceet-linux-gnueabi/linux-stable/4.14-r0/build/defconfig ~/yocto-ktn/layers/meta-<customer>/recipes-kernel/linux/linux-stable/imx/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-stable
code:
devtool modify linux-stable
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-stable
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-stable