Skip to main content
Version: BSP 7.x.y

Host Machine Setup for Building with Yocto

Introduction​

This article provides instructions on how to set up an environment on your machine to Build a Reference Image with Yocto.

To build a Toradex Reference Image with Yocto, you need all the repositories containing the Yocto Layers on which the image depends. This article shows how to obtain all the necessary repositories, keep them up-to-date, and select the correct branch for the BSP version you wish to build.

For information regarding our BSP versions and Yocto images, refer to our BSP Reference Documentation.

Prerequisites​

Toradex uses the repo utility to manage the several git repositories of the BSP and Torizon Meta-Layers.

In the following steps, you will set up repo to configure the meta-layers properly to build your chosen Reference Image with Yocto.

Install Repo Dependencies​

Install the repo dependencies with the command below:

$ sudo apt install curl git python3

After installing Git, configure your user name and e-mail address:

$ git config --global user.name "John Doe"
$ git config --global user.email johndoe@example.com

Install Repo​

Install the repo bootstrap binary:

$  mkdir ~/bin
$  export PATH=~/bin:$PATH
$  curl https://commondatastorage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
$  chmod a+x ~/bin/repo
tip

To make this change persistent across terminal sessions, add ~/bin to your PATH in your ~/.bashrc file:

$  echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
$  source ~/.bashrc

This ensures the repo command is available every time you open a new shell.

Install the Yocto Project Repositories​

To build an image with Yocto, you must clone all the meta-layer repositories necessary to build the image, with all the branches matching the version you wish to build. To clone and manage these repositories, you will use repo, which you have installed in the Prerequisites section. Toradex provides repo manifests, which define which repositories and branches repo must clone for each version to be built. For more details on our manifests, check our BSP Reference Documentation.

To set up the Yocto repositories for building your image, refer to the following subsections according to your needs:

First-time Configuration​

To set up the repos on your machine for the first time, execute the following steps:

  1. Create a directory for your OE-Core setup to live in and clone the meta-information. Replace <version> with any specific release you wish to build. Check the release version in our Embedded Linux Release Matrix.

    $ mkdir ${HOME}/oe-core
    $ cd ${HOME}/oe-core
    $ repo init -u git://git.toradex.com/toradex-manifest.git -b refs/tags/<version> -m tdxref/default.xml
    $ repo sync
    Verdin AM62

    Note that support for the Verdin AM62 v1.1 was not added until version 6.4.0-devel-202309. Therefore, older tags or the default.xml configuration prior to the release of BSP 6.4.0 will not generate a usable image.

  2. Source the file export to setup the environment. On the first invocation, this command also creates a sample configuration in build/conf/.

    $ . export

    Note: Sourcing export configures the shell environment for the current shell session only. You must enter this command whenever you open a new shell session for use with OpenEmbedded.

After sourcing the export file, the first-time configuration is complete, and you can build a reference image.

Update an Existing Configuration​

To update the Yocto repositories, you will need to:

  1. Update the repo manifest to the version you want to work with. To selec the version, you will need to specify its Yocto branch (flag -b) and the manifest (flag -m). See below the branch and manifest combinations for the most common builds:

    • Quarterly releases: -b refs/tags/<version> -m tdxref/default.xml. Substitute <version> for any specific release you wish to build. Check the release version in our Embedded Linux Release Matrix. Also check additional tags in the manifest repository.
    • Monthly releases: -b scarthgap-7.x.y -m tdxref/default.xml. You can also check the list of available branches in our manifest repository.
    • Nightly releases: -b scarthgap-7.x.y -m tdxref/integration.xml. This manifest is for development and testing only. Do not use it for production.

    As an example, run the command below to fetch the repositories for building the Monthly release:

    $ repo init -u git://git.toradex.com/toradex-manifest.git -b scarthgap-7.x.y -m tdxref/default.xml

    Additionally, if you are building the nightly release, make sure to add the following parameter in your conf/local.conf file:

    conf/local.conf
    MACHINEOVERRIDES =. "use-head-next:"

  2. Sync all layers to the version you chose. If you did local changes to any of the layers, you may need to resolve merge conflicts during the sync process.

    $ repo sync

Known Issues During repo Setup​

See additional known issues notes below:

Repo Sync Issues

Due to many company firewalls/proxies only permitting HTTP traffic, our default repo manifest is using. However, the OpenEmbedded or Linaro repositories might show inconsistencies if fetched over HTTP, or their web servers might be under such heavy load. If you get any of the following repo fetch/sync issues:

    error: Unable to find d29dee17d9a95f2ec6b641c234870f3ccbe24102 under http://git.openembedded.org/meta-openembedded
    Cannot obtain needed blob d29dee17d9a95f2ec6b641c234870f3ccbe24102

or:

    error: Unable to find 318f971bb4515a6dcbbb0b87f85f2bc58b6e314f under http://git.linaro.org/git-ro/openembedded/meta-linaro.git
    Cannot obtain needed commit 318f971bb4515a6dcbbb0b87f85f2bc58b6e314f

or:

    fatal: loose object 8807fd141bb73d6b405eff223b3b105613bc809a (stored in /home/user/oe-core/.repo/projects/layers/meta-openembedded.git/objects/88/07fd141bb73d6b405eff223b3b105613bc809a) is corrupt
    error: http://git.openembedded.org/meta-openembedded did not send all necessary objects

First, try repo syncing again. It might only have been a connection glitch.

Then, if the error(s) persist, try using git's garbage collection on the failing repository before attempting to sync again, e.g. if the error indicates an issue in the meta-openembedded repository:

$ cd .repo/projects/layers/meta-openembedded.git
$ git gc

If the error(s) persist try removing your local git/repo cache before attempting to sync again, e.g. if the error indicates an issue in the meta-openembedded repository:

$ rm -rf .repo/projects/layers/meta-openembedded.git
$ rm -rf .repo/project-objects/meta-openembedded.git

Additionally, you can limit the number of downloads of git repositories in parallel using the additional parameter -jX. E.g. to download one repository at a time:

$ repo sync -j1

If your Internet connection permits you might also try switching those failing repositories to using the git protocol instead by modifying your .repo/manifest.xml as follows:

    <remote fetch="git://git.openembedded.org" name="oe"/>
    <remote fetch="git://git.linaro.org/openembedded" name="linaro"/>
Send Feedback!