Toaster User Manual

You need to install the packages that Toaster requires. Use this command:

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

The previous command installs the necessary Toaster modules into a local python 3 cache in your $HOME directory. The caches is actually located in $HOME/.local. To see what packages have been installed into your $HOME directory, do the following:

     $ pip3 list installed --local
                

If you need to remove something, the following works:

     $ pip3 uninstall PackageNameToUninstall
                

Be sure you meet the following requirements:

Perform the following steps to install Toaster:

You can now open up a browser and start using Toaster.

Following are several videos that show how to use the Toaster GUI:

This section only applies if you have set up Toaster for local development, as explained in the "Starting Toaster for Local Development" section.

When you create a project in Toaster, you will be asked to provide a name and to select a Yocto Project release. One of the release options you will find is called "Local Yocto Project".

When you select the "Local Yocto Project" release, Toaster will run your builds using the local Yocto Project clone you have in your computer: the same clone you are using to run Toaster. Unless you manually update this clone, your builds will always use the same Git revision.

If you select any of the other release options, Toaster will fetch the tip of your selected release from the upstream Yocto Project repository every time you run a build. Fetching this tip effectively means that if your selected release is updated upstream, the Git revision you are using for your builds will change. If you are doing development locally, you might not want this change to happen. In that case, the "Local Yocto Project" release might be the right choice.

However, the "Local Yocto Project" release will not provide you with any compatible layers, other than the three core layers that come with the Yocto Project:

If you want to build any other layers, you will need to manually import them into your Toaster project, using the "Import layer" page.

Occasionally, a layer might provide more than one version of the same recipe. For example, the openembedded-core layer provides two versions of the bash recipe (i.e. 3.2.48 and 4.3.30-r0) and two versions of the which recipe (i.e. 2.21 and 2.18). The following figure shows this exact scenario:

By default, the OpenEmbedded build system builds one of the two recipes. For the bash case, version 4.3.30-r0 is built by default. Unfortunately, Toaster as it exists, is not able to override the default recipe version. If you would like to build bash 3.2.48, you need to set the PREFERRED_VERSION variable. You can do so from Toaster, using the "Add variable" form, which is available in the "BitBake variables" page of the project configuration section as shown in the following screen:

To specify bash 3.2.48 as the version to build, enter "PREFERRED_VERSION_bash" in the "Variable" field, and "3.2.48" in the "Value" field. Next, click the "Add variable" button:

After clicking the "Add variable" button, the settings for PREFERRED_VERSION are added to the bottom of the BitBake variables list. With these settings, the OpenEmbedded build system builds the desired version of the recipe rather than the default version:

To use your own layer source, you need to set up the layer source and then tie it into Toaster. This section describes how to tie into a layer index in a manner similar to the way Toaster ties into the OpenEmbedded Metadata Index.

     http://127.0.0.1:8000/admin
                        

     <?xml version="1.0" ?>
     <django-objects version="1.0">
       <object model="orm.toastersetting" pk="100">
                     <field name="name" type="CharField">CUSTOM_LAYERINDEX_SERVER</field>
                     <field name="value" type="CharField">https://layers.my_organization.org/layerindex/branch/master/layers/</field>
       </object>
     <django-objects>
                        

     $ bitbake/lib/toaster/manage.py lsupdates
                        

As shipped, Toaster is configured to use a specific set of releases. Of course, you can always configure Toaster to use any release. For example, you might want your project to build against a specific commit of any of the "out-of-the-box" releases. Or, you might want your project to build against different revisions of OpenEmbedded and BitBake.

As shipped, Toaster is configured to work with the following releases:

The bldcontrol/management/commands/checksettings.py file controls workflow configuration. The following steps outline the process to initially populate this database.

Once these steps complete, Toaster is set up and ready to use.

The pre-set data for Toaster is easily customizable. You can create the orm/fixtures/custom.xml file to customize the values that go into to the database. Customization is additive, and can either extend or completely replace the existing values.

You use the orm/fixtures/custom.xml file to change the default project settings for the machine, distro, file images, and layers. When creating a new project, you can use the file to define the offered alternate project release selections. For example, you can add one or more additional selections that present custom layer sets or distros, and any other local or proprietary content.

Additionally, you can completely disable the content from the oe-core.xml and poky.xml files by defining the section shown below in the settings.xml file. For example, this option is particularly useful if your custom configuration defines fewer releases or layers than the default fixture files.

The following example sets "name" to "CUSTOM_XML_ONLY" and its value to "True".

     <object model="orm.toastersetting" pk="99">
       <field type="CharField" name="name">CUSTOM_XML_ONLY</field>
       <field type="CharField" name="value">True</field>
     </object>
                

The following is an overview of the file format used by the oe-core.xml, poky.xml, and custom.xml files.

The following subsections describe each of the sections in the fixture files, and outline an example section of the XML code. you can use to help understand this information and create a local custom.xml file.

     <!-- Set the project default value for DISTRO -->
     <object model="orm.toastersetting" pk="1">
       <field type="CharField" name="name">DEFCONF_DISTRO</field>
       <field type="CharField" name="value">poky</field>
     </object>
                    

     <!-- Bitbake versions which correspond to the metadata release -->
     <object model="orm.bitbakeversion" pk="1">
       <field type="CharField" name="name">rocko</field>
       <field type="CharField" name="giturl">git://git.yoctoproject.org/poky</field>
       <field type="CharField" name="branch">rocko</field>
       <field type="CharField" name="dirpath">bitbake</field>
     </object>
                    

     <!-- Releases available -->
     <object model="orm.release" pk="1">
       <field type="CharField" name="name">rocko</field>
       <field type="CharField" name="description">Yocto Project 2.4 "Rocko"</field>
       <field rel="ManyToOneRel" to="orm.bitbakeversion" name="bitbake_version">1</field>
       <field type="CharField" name="branch_name">rocko</field>
       <field type="TextField" name="helptext">Toaster will run your builds using the tip of the <a href="http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=rocko">Yocto Project Rocko branch</a>.</field>
     </object>
                    

     <!-- Default project layers for each release -->
     <object model="orm.releasedefaultlayer" pk="1">
       <field rel="ManyToOneRel" to="orm.release" name="release">1</field>
       <field type="CharField" name="layer_name">openembedded-core</field>
     </object>
                    

     <object model="orm.layer" pk="1">
       <field type="CharField" name="name">openembedded-core</field>
       <field type="CharField" name="layer_index_url"></field>
       <field type="CharField" name="vcs_url">git://git.yoctoproject.org/poky</field>
       <field type="CharField" name="vcs_web_url">http://git.yoctoproject.org/cgit/cgit.cgi/poky</field>
       <field type="CharField" name="vcs_web_tree_base_url">http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%</field>
       <field type="CharField" name="vcs_web_file_base_url">http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%</field>
     </object>
     <object model="orm.layer_version" pk="1">
       <field rel="ManyToOneRel" to="orm.layer" name="layer">1</field>
       <field type="IntegerField" name="layer_source">0</field>
       <field rel="ManyToOneRel" to="orm.release" name="release">1</field>
       <field type="CharField" name="branch">rocko</field>
       <field type="CharField" name="dirpath">meta</field>
     </object>
     <object model="orm.layer_version" pk="2">
       <field rel="ManyToOneRel" to="orm.layer" name="layer">1</field>
       <field type="IntegerField" name="layer_source">0</field>
       <field rel="ManyToOneRel" to="orm.release" name="release">2</field>
       <field type="CharField" name="branch">HEAD</field>
       <field type="CharField" name="commit">HEAD</field>
       <field type="CharField" name="dirpath">meta</field>
     </object>
     <object model="orm.layer_version" pk="3">
       <field rel="ManyToOneRel" to="orm.layer" name="layer">1</field>
       <field type="IntegerField" name="layer_source">0</field>
       <field rel="ManyToOneRel" to="orm.release" name="release">3</field>

       <field type="CharField" name="branch">master</field>
       <field type="CharField" name="dirpath">meta</field>
     </object>
                    

Before you use remote Toaster monitoring, you should do a health check. To do this, ping the Toaster server using the following call to see if it is still alive:

     http://host:port/health
                

Be sure to provide values for host and port. If the server is alive, you will get the response HTML:

     <!DOCTYPE html>
     <html lang="en">
       <head><title>Toaster Health</title></head>
       <body>Ok</body>
     </html>
                

Sometimes it is useful to determine the status of a build in progress. To get the status of pending builds, use the following call:

     http://host:port/toastergui/api/building
                

Be sure to provide values for host and port. The output is a JSON file that itemizes all builds in progress. This file includes the time in seconds since each respective build started as well as the progress of the cloning, parsing, and task execution. The following is sample output for a build in progress:

     {"count": 1,
      "building": [
        {"machine": "beaglebone",
           "seconds": "463.869",
           "task": "927:2384",
           "distro": "poky",
           "clone": "1:1",
           "id": 2,
           "start": "2017-09-22T09:31:44.887Z",
           "name": "20170922093200",
           "parse": "818:818",
           "project": "my_rocko",
           "target": "core-image-minimal"
           }]
     }
                

The JSON data for this query is returned in a single line. In the previous example the line has been artificially split for readability.

Once a build is completed, you get the status when you use the following call:

     http://host:port/toastergui/api/builds
                

Be sure to provide values for host and port. The output is a JSON file that itemizes all complete builds, and includes build summary information. The following is sample output for a completed build:

     {"count": 1,
      "builds": [
        {"distro": "poky",
           "errors": 0,
           "machine":
           "beaglebone",
           "project": "my_rocko",
           "stop": "2017-09-22T09:26:36.017Z",
           "target": "quilt-native",
           "seconds": "78.193",
           "outcome": "Succeeded",
           "id": 1,
           "start": "2017-09-22T09:25:17.824Z",
           "warnings": 1,
           "name": "20170922092618"
           }]
     }
                

The JSON data for this query is returned in a single line. In the previous example the line has been artificially split for readability.

Sometimes it is useful to determine the status of a specific build. To get the status of a specific build, use the following call:

     http://host:port/toastergui/api/build/ID
                

Be sure to provide values for host, port, and ID. You can find the value for ID from the Builds Completed query. See the "Checking Status of Builds Completed" section for more information.

The output is a JSON file that itemizes the specific build and includes build summary information. The following is sample output for a specific build:

     {"build":
       {"distro": "poky",
        "errors": 0,
        "machine": "beaglebone",
        "project": "my_rocko",
        "stop": "2017-09-22T09:26:36.017Z",
        "target": "quilt-native",
        "seconds": "78.193",
        "outcome": "Succeeded",
        "id": 1,
        "start": "2017-09-22T09:25:17.824Z",
        "warnings": 1,
        "name": "20170922092618",
        "cooker_log": "/opt/user/poky/build-toaster-2/tmp/log/cooker/beaglebone/build_20170922_022607.991.log"
        }
     }
                

The JSON data for this query is returned in a single line. In the previous example the line has been artificially split for readability.

The buildslist command lists all builds that Toaster has recorded. Access the command as follows:

     $ bitbake/lib/toaster/manage.py buildslist
                

The command returns a list, which includes numeric identifications, of the builds that Toaster has recorded in the current database.

You need to run the buildslist command first to identify existing builds in the database before using the builddelete command. Here is an example that assumes default repository and build directory names:

     $ cd ~/poky/build
     $ python ../bitbake/lib/toaster/manage.py buildslist
                

If your Toaster database had only one build, the above buildslist command would return something like the following:

     1: qemux86 poky core-image-minimal
                

The builddelete command deletes data associated with a build. Access the command as follows:

     $ bitbake/lib/toaster/manage.py builddelete build_id
                

The command deletes all the build data for the specified build_id. This command is useful for removing old and unused data from the database.

Prior to running the builddelete command, you need to get the ID associated with builds by using the buildslist command.

The perf command measures Toaster performance. Access the command as follows:

     $ bitbake/lib/toaster/manage.py perf
                

The command is a sanity check that returns page loading times in order to identify performance problems.

The checksettings command verifies existing Toaster settings. Access the command as follows:

     $ bitbake/lib/toaster/manage.py checksettings
                

Toaster uses settings that are based on the database to configure the building tasks. The checksettings command verifies that the database settings are valid in the sense that they have the minimal information needed to start a build.

In order for the checksettings command to work, the database must be correctly set up and not have existing data. To be sure the database is ready, you can run the following:

     $ bitbake/lib/toaster/mana​ge.py syncdb
     $ bitbake/lib/toaster/mana​ge.py migrate orm
     $ bitbake/lib/toaster/mana​ge.py migrate bldcontrol
                

After running these commands, you can run the checksettings command.

The runbuilds command launches scheduled builds. Access the command as follows:

     $ bitbake/lib/toaster/manage.py runbuilds
                

The runbuilds command checks if scheduled builds exist in the database and then launches them per schedule. The command returns after the builds start but before they complete. The Toaster Logging Interface records and updates the database when the builds complete.