Toaster setup and usage

Toaster installation

Toaster is a web interface that helps manage Yocto builds.

User manual can be found at: https://www.yoctoproject.org/docs/current/toaster-manual/toaster-manual.html

First of all checkout a Poky version on your host. We use thud revision in this page. Note that Toaster version is the same as the checked-out Poky version.

$ git clone git://git.yoctoproject.org/poky -b thud

Then install python3-pip. On Ubuntu:

$ sudo apt-get install python3-pip

Install required components to run Toaster:

$ cd poky
$ pip3 install --user -r bitbake/toaster-requirements.txt

Then we are ready to start using toaster.

Toaster start and stop

To start Toaster for local usage execute these commands into poky directory:

$ source oe-init-build-env
$ source toaster start

If we want to enable access to Toaster admin page, we need also this command from the same terminal (only one time):

$ ../bitbake/lib/toaster/manage.py createsuperuser

To stop Toaster (on the same terminal where start command was launched):

$ source toaster stop

Toaster usage

Toaster can be used to do a build from scratch or to monitor builds executed from same command line where Toaster was lauched. Old builds executed outside Toaster can also be imported and managed by Toaster.

To start using Toaster, connect with a web browser to http://127.0.0.1:8000

Create a new build from Toaster

Click "New project" button in the right-top of the screen, insert a project name and select a Yocto release to use to build artefacts. Note that if you choose "Local Yocto Project" you'll have to checkout and import additional layers manually, even if they are from OpenEmbedded. Yocto release selected is checked out locally at tip version every time a build will be launched.

Then, start customizing the build configuring machine, distro, adding layers and finally starting a image creation from "Image recipes" page.

At the end of the process, you can browse build results: packages, executed tasks, statistics, image files and kernel artefacts etc.

Start a tracked build from command line

This must be done from the same terminal from where Toaster was started.

Simply do the same things when using Bitbake from command line:

$ source oe-init-build-env BUILD_DIR
EDIT local.conf, bblayers.conf etc.
$ bitbake IMAGE_NAME

In Toaster you will see your build progress under the "Command line builds" project. You cannot start or stop this build from toaster, but only from command line.

At the end of the process, you can browse a limited set of build results: image files and kernel artefacts, executed tasks, built recipes.

Start an untracked build from command line

This is done from a generic terminal.

$ cd poky
$ source oe-init-build-env BUILD_DIR
EDIT local.conf, bblayers.conf etc.
$ bitbake IMAGE_NAME

In this case, Toaster is not aware of your build. But at a later time you can import it in Toaster.

Click on "New project", type a name and select "Import command line project", then specify the build path.

Starting from now, this project will be treated and managed exactly as a project created from Toaster: layer browsing functionality is active, and a local checkout of Poky release is done for every build. Only configuration is used from imported build.

Build remains in original directory, no local copies were made.

NOTE: Poky release selected for imported projects is assigned automatically and seems to be the oldest from the Yocto releases handled by Toaster.

General notes

• In the Poky directory tree build, directories for Toaster generated projects have "anonymous" names, so there is no possibility to know which project is contained in that directory without using Toaster.

• In thud version if a project import fails subsequent imports will fail with the same error until toaster restart.

• In thud version when a build of a imported project is stopped from Toaster, an anonymous failed build reporting only the hour and the build time appears in "Command line projects"

• If this message comes out at Toaster start:

Your models have changes that are not yet reflected in a migration, and so won't be applied.
Run 'manage.py makemigrations' to make new migrations, and then re-run 'manage.py migrate' to apply them.

probably Toaster was not kindly stopped in the past. We need to launch:

$ ../bitbake/lib/toaster/manage.py makemigrations
$ ../bitbake/lib/toaster/manage.py migrate

from the same shell where toaster was launched.

• It we want to build projects generated from Toaster also from command line, we need to check "Merged Toaster settings (Command line user compatibility)" to have Toaster settings appended to local.conf and bblayers.conf. Otherwise Toaster will not touch these files, generating toaster.conf and toaster_bblayers.conf to manage its customizations.

Final considerations

Toaster is a nice tool that can help to understand how Yocto works and to know the plethora of kinds that Yocto can manage (machines, layers, recipes, images...). Conversely, using it during development can be a little tricky, due to the fact that it is not so straightforward mixing builds started from command line and from Toaster. Maybe the best from this tool can be obtained using it on a remote server with a stable build environment (fixed Poky version and stable custom layers) to allow multiple users build and download images without give them the access to the server and require them to deal with a console, or to stay updated with latest fixes on selected Poky revision.