Skip to content

# 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

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

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.

Hint

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 of your `ida_rsa.pub` file from the previous step and paste it in the "Key" input field. Click "Add Key".

## Cloning repositories

### 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 ~

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-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 configuration and `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 `build-stm32mp` (or `build-<customer>`for full 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:

- repo.conf
  It contains information which meta-layers in which version should be fetched and placed in the `yocto-ktn/layers` subdirectory. This file is special to the Kontron BSPs and `init-env` tool.
- bblayers.conf
  is the yocto configuration file to configure which directories contain recipes to use
- local.conf
  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:

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/poky` or `layers/openembedded-core`

   1. Initialize the yocto 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` command.

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

With the `-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 `rel_BSP_stm32mp_1.3.0`.

Important

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

If you have a full customized boards use your customized build repository `build-<customer>`:

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

    . 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 `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:

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.