%poky; ] > In order to configure and use Toaster, you should understand some concepts and have some basic command reference material available. This final chapter provides conceptual information on layer sources, releases, and JSON configuration files. Also provided is a quick look at some useful manage.py commands that are Toaster-specific. Information on manage.py commands does exist across the Web and the information in this manual by no means attempts to provide a command comprehensive reference.

In general, a "layer source" is a source of information about existing layers. In particular, we are concerned with layers that you can use with the Yocto Project and Toaster. This chapter describes a particular type of layer source called a "layer index." A layer index is a web application that contains information about a set of custom layers. A good example of an existing layer index is the OpenEmbedded Metadata Index. A public instance of this layer index exists at . You can find the code for this layer index's web application at . When you tie a layer source into Toaster, it can query the layer source through a REST API, store the information about the layers in the Toaster database, and then show the information to users. Users are then able to view that information and build layers from Toaster itself without worrying about cloning or editing the BitBake layers configuration file bblayers.conf. Tying a layer source into Toaster is convenient when you have many custom layers that need to be built on a regular basis by a community of developers. In fact, Toaster comes pre-configured with the OpenEmbedded Metadata Index. You do not have to use a layer source to use Toaster. Tying into a layer source is optional.

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.

The obvious first step for using a layer index is to have several custom layers that developers build and access using the Yocto Project on a regular basis. This set of layers needs to exist and you need to be familiar with where they reside. You will need that information when you set up the code for the web application that "hooks" into your set of layers. For general information on layers, see the "BSP Layers" and "Using the Yocto Project's BSP Tools" sections in the Yocto Project Board Support Package (BSP) Developer's Guide.

If you want Toaster to use your layer index, you must host the web application in a server to which Toaster can connect. You also need to give Toaster the information about your layer index. In other words, you have to configure Toaster to use your layer index. This section describes two methods by which you can configure and use your layer index. In the previous section, the code for the OpenEmbedded Metadata Index (i.e. ) was referenced. You can use this code, which is at , as a base to create your own layer index.

Access the administration interface through a browser by entering the URL of your Toaster instance and adding "/admin" to the end of the URL. As an example, if you are running Toaster locally, use the following URL: http://127.0.0.1:8000/admin The administration interface has a "Layer sources" section that includes an "Add layer source" button. Click that button and provide the required information. Make sure you select "layerindex" as the layer source type.

The Django fixture feature overrides the default layer server when you use it to specify a custom URL. To use the fixture feature, create (or edit) the file bitbake/lib/toaster.orm/fixtures/custom.xml, and then set the following Toaster setting to your custom URL: <?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> When you start Toaster for the first time, or if you delete the file toaster.sqlite and restart, the database will populate cleanly from this layer index server. Once the information has been updated, verify the new layer information is available by using the Toaster web interface. To do that, visit the "All compatible layers" page inside a Toaster project. The layers from your layer source should be listed there. If you change the information in your layer index server, refresh the Toaster database by running the following command: $ bitbake/lib/toaster/manage.py lsupdates If Toaster can reach the API URL, you should see a message telling you that Toaster is updating the layer source information.

When you create a Toaster project using the web interface, you are asked to choose a "Release." In the context of Toaster, the term "Release" refers to a set of layers and a BitBake version the OpenEmbedded build system uses to build something. As shipped, Toaster is pre-configured with releases that correspond to Yocto Project release branches. However, you can modify, delete, and create new releases according to your needs. This section provides some background information on releases.

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: Yocto Project &DISTRO; "&DISTRO_NAME;" or OpenEmbedded "&DISTRO_NAME;": This release causes your Toaster projects to build against the head of the &DISTRO_NAME_NO_CAP; branch at or . Yocto Project "Master" or OpenEmbedded "Master": This release causes your Toaster Projects to build against the head of the master branch, which is where active development takes place, at or . Local Yocto Project or Local OpenEmbedded: This release causes your Toaster Projects to build against the head of the poky or openembedded-core clone you have local to the machine running Toaster.

A release consists of the following: Name: The name of the release (name). This release name never appears in the the Toaster web interface. Consequently, a user never sees the release name. Description: The textual description of the release (description). This description is what users encounter when creating projects with the Toaster web interface. When you configure your release, be sure to use a description that sufficiently describes and is understandable. If Toaster has more than one release configured, the release descriptions appear listed in a drop down menu when a user creates a new project. If Toaster has only one release configured, all projects created using the web interface take that release and the drop down menu does not display in the Toaster web interface. BitBake: The Bitbake version (bitbake) used to build layers set in the current release. This version is described by a name, a Git URL, a branch in the Git URL, and a directory path in the Git repository. As an example, consider the following snippet from a Toaster JSON configuration file. This BitBake version uses the master branch from the OpenEmbedded repository: "bitbake" : [ { "name": "master", "giturl": "git://git.openembedded.org/bitbake", "branch": "master", "dirpath": "" } ] Here is more detail on each of the items that comprise the BitBake version: Name: A string (name) used to refer to the version of BitBake you are using with Toaster. This name is never exposed through Toaster. Git URL: The URL (giturl) for the BitBake Git repository cloned for Toaster projects. Branch: The Git branch, or revision, (branch) of the BitBake repository used with Toaster. Directory Path: The sub-directory of the BitBake repository (dirpath). If the Git URL includes more than one repository, you need to set this directory. If the URL does not include more than a single repository, you can set dirpath to a null string (i.e. ""). Branch: The branch for the layer source (branch) used with the release. For example, for the OpenEmbedded layer source, the "master", "fido", and "jethro" branches are available. Default Layers: The set of default layers (defaultlayers) automatically added to the project configuration when a project is created. Layer Source Priorities A specification of layer source priorities (layersourcepriority). In order for Toaster to work as intended, the "Imported layers" layer source should have the highest priority, which means that layers manually imported by users with the "Import layer" functionality will always be visible and available for selection. Help Text: Help text (helptext) that explains what the release does when selected. This help text appears below the release drop-down menu when you create a Toaster project. The help text should assist users in making the correct decision regarding the release to use for a given project. To summarize what comprises a release, consider the following example from a Toaster JSON file. The configuration names the release "master" and uses the "master" branch provided by the layer source of type "layerindex", which is called "OpenEmbedded", and sets the openembedded-core layer as the one to be added by default to any projects created in Toaster. The BitBake version used would be defined as shown earlier in the previous list: "releases": [ { "name": "master", "description": "OpenEmbedded master", "bitbake": "master", "branch": "master", "defaultlayers": [ "openembedded-core" ], "layersourcepriority": { "Imported layers": 99, "Local OpenEmbedded" : 10, "OpenEmbedded" : 0 }, "helptext": "Toaster will run your builds using the tip of the <a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/\">Yocto Project master branch</a>, where active development takes place. This is not a stable branch, so your builds might not work as expected." } ]

You must configure Toaster before using it. Configuration customizes layer source settings and Toaster defaults for all users and is performed by the person responsible for Toaster Configuration (i.e the Toaster Administrator). The Toaster Administrator performs this configuration through the Django administration interface. By convention, the supplied configuration files are named toasterconf.json. The Toaster Administrator can customize the file prior to loading it into Toaster. The TOASTER_CONF variable in the Toaster startup script at bitbake/bin/toaster specifies the location of the toasterconf.json file.

Two versions of the configuration file exist: The meta-poky/conf/toasterconf.json in the conf directory of the Yocto Project's meta-poky layer. This version contains the default Yocto Project configuration for Toaster. You are prompted to select this file during the Toaster set up process if you cloned the poky repository (i.e. &YOCTO_GIT_URL;/poky). The meta/conf/toasterconf.json in the conf directory of the OpenEmbedded's openembedded-core layer. This version contains the default OpenEmbedded configuration for Toaster. You are prompted to select this file during the Toaster set up process if you had cloned the openembedded-core repository (i.e. git://git.openembedded.org/openembedded-core).

The toasterconf.json file consists of easily readable areas: configuration, layer sources, BitBake, default release, and releases.

This area of the JSON file sets which variables are exposed to users through the Toaster web interface. Users can easily edit these variables. The variables you set here are displayed in the "Configuration variables" page in Toaster. Minimally, you should set the MACHINE variable, which appears to users as part of the project page in Toaster. Here is the default config area: "config": { "MACHINE" : "qemux86", "DISTRO" : "poky", "IMAGE_FSTYPES": "ext3 jffs2 tar.bz2", "IMAGE_INSTALL_append": "", "PACKAGE_CLASSES": "package_rpm", },

This area of the JSON file defines the layer sources Toaster uses. Toaster reads layer information from layer sources. Three types of layer sources exist that Toaster recognizes: Local, LayerIndex, and Imported. The Local layer source reads layers from Git clones available on your local drive. Using a local layer source enables you to easily test Toaster. If you are setting up a hosted version of Toaster, it does not make sense to have a local layer source. The LayerIndex layer source uses a REST API exposed by instances of the Layer Index application (e.g the public ) to read layer data. The Imported layer source is reserved for layer data manually introduced by the user or Toaster Administrator through the GUI. This layer source lets users import their own layers and build them with Toaster. You should not remove the imported layer source. Here is the default layersources area: "layersources": [ { "name": "Local Yocto Project", "sourcetype": "local", "apiurl": "../../", "branches": ["HEAD" ], "layers": [ { "name": "openembedded-core", "local_path": "meta", "vcs_url": "remote:origin", "dirpath": "meta" }, { "name": "meta-poky", "local_path": "meta-poky", "vcs_url": "remote:origin", "dirpath": "meta-poky" }, { "name": "meta-yocto-bsp", "local_path": "meta-yocto-bsp", "vcs_url": "remote:origin", "dirpath": "meta-yocto-bsp" } ] }, { "name": "OpenEmbedded", "sourcetype": "layerindex", "apiurl": "http://layers.openembedded.org/layerindex/api/", "branches": ["master", "jethro" ,"fido"] }, { "name": "Imported layers", "sourcetype": "imported", "apiurl": "", "branches": ["master", "jethro","fido", "HEAD"] } ],

This area of the JSON file defines the version of BitBake Toaster uses. As shipped, Toaster is configured to recognize four versions of BitBake: master, fido, jethro, and HEAD. HEAD is a special option that builds whatever is available on disk, without checking out any remote Git repositories. Here is the default bitbake area: "bitbake" : [ { "name": "master", "giturl": "remote:origin", "branch": "master", "dirpath": "bitbake" }, { "name": "jethro", "giturl": "remote:origin", "branch": "jethro", "dirpath": "bitbake" }, { "name": "fido", "giturl": "remote:origin", "branch": "fido", "dirpath": "bitbake" }, { "name": "HEAD", "giturl": "remote:origin", "branch": "HEAD", "dirpath": "bitbake" } ],

This area of the JSON file establishes a default release used by Toaster. As shipped, Toaster uses the "master" release. Here is the statement in the JSON file that establishes the default release: "defaultrelease": "master",

This area of the JSON file defines the versions of the OpenEmbedded build system Toaster recognizes. As shipped, Toaster is configured to work with the four releases described in the "Pre-Configured Releases" section. Here is the default releases area: "releases": [ { "name": "master", "description": "Yocto Project master", "bitbake": "master", "branch": "master", "defaultlayers": [ "openembedded-core", "meta-poky", "meta-yocto-bsp"], "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 }, "helptext": "Toaster will run your builds using the tip of the <a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/\">Yocto Project master branch</a>, where active development takes place. This is not a stable branch, so your builds might not work as expected." }, { "name": "jethro", "description": "Yocto Project 2.0 Jethro", "bitbake": "jethro", "branch": "jethro", "defaultlayers": [ "openembedded-core", "meta-poky", "meta-yocto-bsp"], "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 }, "helptext": "Toaster will run your builds with the tip of the <a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=jethro\">Yocto Project 2.0 \"Jethro\"</a> branch." }, { "name": "fido", "description": "Yocto Project 1.8 Fido", "bitbake": "fido", "branch": "fido", "defaultlayers": [ "openembedded-core", "meta-poky", "meta-yocto-bsp"], "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 }, "helptext": "Toaster will run your builds with the tip of the <a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=fido\">Yocto Project 1.8 \"Fido\"</a> branch." }, { "name": "local", "description": "Local Yocto Project", "bitbake": "HEAD", "branch": "HEAD", "defaultlayers": [ "openembedded-core", "meta-poky", "meta-yocto-bsp"], "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 }, "helptext": "Toaster will run your builds with the version of the Yocto Project you have cloned or downloaded to your computer." } ]

Toaster has an API that allows remote management applications to directly query the state of the Toaster server and its builds in a machine-to-machine manner. This API uses the REST interface and the transfer of JSON files. For example, you might monitor a build inside a container through well supported known HTTP ports in order to easily access a Toaster server inside the container. In this example, when you use this direct JSON API, you avoid having web page parsing against the display the user sees.

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> In the previous example, the actual output appears in a single line. Here, however, the line has been artificially split for readability.

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" }] }

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" }] }

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" } }

In addition to the web user interface and the scripts that start and stop Toaster, command-line commands exist through the manage.py management script. You can find general documentation on manage.py at the Django site. However, several manage.py commands have been created that are specific to Toaster and are used to control configuration and back-end tasks. You can locate these commands in the Source Directory (e.g. poky) at bitbake/lib/manage.py. This section documents those commands. When using manage.py commands given a default configuration, you must be sure that your working directory is set to the Build Directory. Using manage.py commands from the Build Directory allows Toaster to find the toaster.sqlite file, which is located in the Build Directory. For non-default database configurations, it is possible that you can use manage.py commands from a directory other than the Build directory. To do so, the toastermain/settings.py file must be configured to point to the correct database backend.

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.