Gitiles
Code Review Sign In
gerrit.openbmc.org / openbmc / openbmc / 4873add6e11c1bd421c83cd08df589f1184aa673 / . / poky / documentation / toaster-manual / toaster-manual-reference.xml
blob: ae267f41848a053e74b0a8b19a7dcf49cd411393 [file] [log] [blame]
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
<chapter id='toaster-manual-reference'>
<title>Concepts and Reference</title>
<para>
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
<filename>manage.py</filename> commands that are Toaster-specific.
Information on <filename>manage.py</filename> commands does exist
across the Web and the information in this manual by no means
attempts to provide a command comprehensive reference.
</para>
<section id='layer-source'>
<title>Layer Source</title>
<para>
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."
</para>
<para>
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 Layer Index.
A public instance of this layer index exists at
<ulink url='http://layers.openembedded.org'></ulink>.
You can find the code for this layer index's web application at
<ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/layerindex-web/'></ulink>.
</para>
<para>
When you tie a layer source into Toaster, it can query the layer
source through a
<ulink url='http://en.wikipedia.org/wiki/Representational_state_transfer'>REST</ulink>
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
<filename>bblayers.conf</filename>.
</para>
<para>
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.
<note>
You do not have to use a layer source to use Toaster.
Tying into a layer source is optional.
</note>
</para>
<section id='layer-source-using-with-toaster'>
<title>Setting Up and Using a Layer Source</title>
<para>
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.
</para>
<section id='understanding-your-layers'>
<title>Understanding Your Layers</title>
<para>
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.
</para>
<para>
For general information on layers, see the
"<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
section in the Yocto Project Overview and Concepts Manual.
For information on how to create layers, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
section in the Yocto Project Development Tasks Manual.
</para>
</section>
<section id='configuring-toaster-to-hook-into-your-layer-source'>
<title>Configuring Toaster to Hook Into Your Layer Index</title>
<para>
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.
</para>
<para>
In the previous section, the code for the OpenEmbedded
Metadata Index (i.e.
<ulink url='http://layers.openembedded.org'></ulink>) was
referenced.
You can use this code, which is at
<ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/layerindex-web/'></ulink>,
as a base to create your own layer index.
</para>
<section id='use-the-administration-interface'>
<title>Use the Administration Interface</title>
<para>
Access the administration interface through a
browser by entering the URL of your Toaster instance and
adding "<filename>/admin</filename>" to the end of the
URL.
As an example, if you are running Toaster locally, use
the following URL:
<literallayout class='monospaced'>
http://127.0.0.1:8000/admin
</literallayout>
</para>
<para>
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.
</para>
</section>
<section id='use-the-fixture-feature'>
<title>Use the Fixture Feature</title>
<para>
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
<filename>bitbake/lib/toaster.orm/fixtures/custom.xml</filename>,
and then set the following Toaster setting to your
custom URL:
<literallayout class='monospaced'>
&lt;?xml version="1.0" ?&gt;
&lt;django-objects version="1.0"&gt;
&lt;object model="orm.toastersetting" pk="100"&gt;
&lt;field name="name" type="CharField"&gt;CUSTOM_LAYERINDEX_SERVER&lt;/field&gt;
&lt;field name="value" type="CharField"&gt;https://layers.my_organization.org/layerindex/branch/master/layers/&lt;/field&gt;
&lt;/object&gt;
&lt;django-objects&gt;
</literallayout>
When you start Toaster for the first time, or if you
delete the file <filename>toaster.sqlite</filename> and restart,
the database will populate cleanly from this layer index server.
</para>
<para>
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.
</para>
<para>
If you change the information in your layer index server,
refresh the Toaster database by running the following command:
<literallayout class='monospaced'>
$ bitbake/lib/toaster/manage.py lsupdates
</literallayout>
If Toaster can reach the API URL, you should see a message
telling you that Toaster is updating the layer source information.
</para>
</section>
</section>
</section>
</section>
<section id='toaster-releases'>
<title>Releases</title>
<para>
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.
</para>
<section id='toaster-releases-supported'>
<title>Pre-Configured Releases</title>
<para>
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.
</para>
<para>
As shipped, Toaster is configured to work with the following
releases:
<itemizedlist>
<listitem><para><emphasis>
Yocto Project &DISTRO; "&DISTRO_NAME;" or OpenEmbedded "&DISTRO_NAME;":</emphasis>
This release causes your Toaster projects to build
against the head of the &DISTRO_NAME_NO_CAP; branch at
<ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/?h=rocko'></ulink>
or <ulink url='http://git.openembedded.org/openembedded-core/commit/?h=rocko'></ulink>.
</para></listitem>
<listitem><para><emphasis>Yocto Project "Master" or OpenEmbedded "Master":</emphasis>
This release causes your Toaster Projects to
build against the head of the master branch, which is
where active development takes place, at
<ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/'></ulink>
or
<ulink url='http://git.openembedded.org/openembedded-core/log/'></ulink>.
</para></listitem>
<listitem><para><emphasis>Local Yocto Project or Local OpenEmbedded:</emphasis>
This release causes your Toaster Projects to
build against the head of the <filename>poky</filename>
or <filename>openembedded-core</filename> clone you
have local to the machine running Toaster.
</para></listitem>
</itemizedlist>
</para>
</section>
</section>
<section id='configuring-toaster'>
<title>Configuring Toaster</title>
<para>
In order to use Toaster, you must configure the database with the
default content. The following subsections describe various aspects
of Toaster configuration.
</para>
<section id='configuring-the-workflow'>
<title>Configuring the Workflow</title>
<para>
The
<filename>bldcontrol/management/commands/checksettings.py</filename>
file controls workflow configuration.
The following steps outline the process to initially populate
this database.
<orderedlist>
<listitem><para>
The default project settings are set from
<filename>orm/fixtures/settings.xml</filename>.
</para></listitem>
<listitem><para>
The default project distro and layers are added
from <filename>orm/fixtures/poky.xml</filename> if poky
is installed.
If poky is not installed, they are added
from <filename>orm/fixtures/oe-core.xml</filename>.
</para></listitem>
<listitem><para>
If the <filename>orm/fixtures/custom.xml</filename> file
exists, then its values are added.
</para></listitem>
<listitem><para>
The layer index is then scanned and added to the database.
</para></listitem>
</orderedlist>
Once these steps complete, Toaster is set up and ready to use.
</para>
</section>
<section id='customizing-pre-set-data'>
<title>Customizing Pre-Set Data</title>
<para>
The pre-set data for Toaster is easily customizable. You can
create the <filename>orm/fixtures/custom.xml</filename> file
to customize the values that go into to the database.
Customization is additive,
and can either extend or completely replace the existing values.
</para>
<para>
You use the <filename>orm/fixtures/custom.xml</filename> 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.
</para>
<para>
Additionally, you can completely disable the content from the
<filename>oe-core.xml</filename> and <filename>poky.xml</filename>
files by defining the section shown below in the
<filename>settings.xml</filename> file.
For example, this option is particularly useful if your custom
configuration defines fewer releases or layers than the default
fixture files.
</para>
<para>
The following example sets "name" to "CUSTOM_XML_ONLY" and its value
to "True".
<literallayout class='monospaced'>
&lt;object model="orm.toastersetting" pk="99"&gt;
&lt;field type="CharField" name="name"&gt;CUSTOM_XML_ONLY&lt;/field&gt;
&lt;field type="CharField" name="value"&gt;True&lt;/field&gt;
&lt;/object&gt;
</literallayout>
</para>
</section>
<section id='understanding-fixture-file-format'>
<title>Understanding Fixture File Format</title>
<para>
The following is an overview of the file format used by the
<filename>oe-core.xml</filename>, <filename>poky.xml</filename>,
and <filename>custom.xml</filename> files.
</para>
<para>
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
<filename>custom.xml</filename> file.
</para>
<section id='defining-the-default-distro-and-other-values'>
<title>Defining the Default Distro and Other Values</title>
<para>
This section defines the default distro value for new projects.
By default, it reserves the first Toaster Setting record "1".
The following demonstrates how to set the project default value
for
<ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>:
<literallayout class='monospaced'>
&lt;!-- Set the project default value for DISTRO --&gt;
&lt;object model="orm.toastersetting" pk="1"&gt;
&lt;field type="CharField" name="name"&gt;DEFCONF_DISTRO&lt;/field&gt;
&lt;field type="CharField" name="value"&gt;poky&lt;/field&gt;
&lt;/object&gt;
</literallayout>
You can override other default project values by adding
additional Toaster Setting sections such as any of the
settings coming from the <filename>settings.xml</filename>
file.
Also, you can add custom values that are included in the
BitBake environment.
The "pk" values must be unique.
By convention, values that set default project values have a
"DEFCONF" prefix.
</para>
</section>
<section id='defining-bitbake-version'>
<title>Defining BitBake Version</title>
<para>
The following defines which version of BitBake is used
for the following release selection:
<literallayout class='monospaced'>
&lt;!-- Bitbake versions which correspond to the metadata release --&gt;
&lt;object model="orm.bitbakeversion" pk="1"&gt;
&lt;field type="CharField" name="name"&gt;rocko&lt;/field&gt;
&lt;field type="CharField" name="giturl"&gt;git://git.yoctoproject.org/poky&lt;/field&gt;
&lt;field type="CharField" name="branch"&gt;rocko&lt;/field&gt;
&lt;field type="CharField" name="dirpath"&gt;bitbake&lt;/field&gt;
&lt;/object&gt;
</literallayout>
</para>
</section>
<section id='defining-releases'>
<title>Defining Release</title>
<para>
The following defines the releases when you create a new
project.
<literallayout class='monospaced'>
&lt;!-- Releases available --&gt;
&lt;object model="orm.release" pk="1"&gt;
&lt;field type="CharField" name="name"&gt;rocko&lt;/field&gt;
&lt;field type="CharField" name="description"&gt;Yocto Project 2.4 "Rocko"&lt;/field&gt;
&lt;field rel="ManyToOneRel" to="orm.bitbakeversion" name="bitbake_version"&gt;1&lt;/field&gt;
&lt;field type="CharField" name="branch_name"&gt;rocko&lt;/field&gt;
&lt;field type="TextField" name="helptext"&gt;Toaster will run your builds using the tip of the &lt;a href="http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=rocko"&gt;Yocto Project Rocko branch&lt;/a&gt;.&lt;/field&gt;
&lt;/object&gt;
</literallayout>
The "pk" value must match the above respective BitBake
version record.
</para>
</section>
<section id='defining-the-release-default-layer-names'>
<title>Defining the Release Default Layer Names</title>
<para>
The following defines the default layers for each release:
<literallayout class='monospaced'>
&lt;!-- Default project layers for each release --&gt;
&lt;object model="orm.releasedefaultlayer" pk="1"&gt;
&lt;field rel="ManyToOneRel" to="orm.release" name="release"&gt;1&lt;/field&gt;
&lt;field type="CharField" name="layer_name"&gt;openembedded-core&lt;/field&gt;
&lt;/object&gt;
</literallayout>
The 'pk' values in the example above should start at "1" and increment
uniquely.
You can use the same layer name in multiple releases.
</para>
</section>
<section id='defining-layer-definitions'>
<title>Defining Layer Definitions</title>
<para>
Layer definitions are the most complex.
The following defines each of the layers, and then defines the exact layer
version of the layer used for each respective release.
You must have one <filename>orm.layer</filename>
entry for each layer.
Then, with each entry you need a set of
<filename>orm.layer_version</filename> entries that connects
the layer with each release that includes the layer.
In general all releases include the layer.
<literallayout class='monospaced'>
&lt;object model="orm.layer" pk="1"&gt;
&lt;field type="CharField" name="name"&gt;openembedded-core&lt;/field&gt;
&lt;field type="CharField" name="layer_index_url"&gt;&lt;/field&gt;
&lt;field type="CharField" name="vcs_url"&gt;git://git.yoctoproject.org/poky&lt;/field&gt;
&lt;field type="CharField" name="vcs_web_url"&gt;http://git.yoctoproject.org/cgit/cgit.cgi/poky&lt;/field&gt;
&lt;field type="CharField" name="vcs_web_tree_base_url"&gt;http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%&lt;/field&gt;
&lt;field type="CharField" name="vcs_web_file_base_url"&gt;http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%&lt;/field&gt;
&lt;/object&gt;
&lt;object model="orm.layer_version" pk="1"&gt;
&lt;field rel="ManyToOneRel" to="orm.layer" name="layer"&gt;1&lt;/field&gt;
&lt;field type="IntegerField" name="layer_source"&gt;0&lt;/field&gt;
&lt;field rel="ManyToOneRel" to="orm.release" name="release"&gt;1&lt;/field&gt;
&lt;field type="CharField" name="branch"&gt;rocko&lt;/field&gt;
&lt;field type="CharField" name="dirpath"&gt;meta&lt;/field&gt;
&lt;/object&gt;
&lt;object model="orm.layer_version" pk="2"&gt;
&lt;field rel="ManyToOneRel" to="orm.layer" name="layer"&gt;1&lt;/field&gt;
&lt;field type="IntegerField" name="layer_source"&gt;0&lt;/field&gt;
&lt;field rel="ManyToOneRel" to="orm.release" name="release"&gt;2&lt;/field&gt;
&lt;field type="CharField" name="branch"&gt;HEAD&lt;/field&gt;
&lt;field type="CharField" name="commit"&gt;HEAD&lt;/field&gt;
&lt;field type="CharField" name="dirpath"&gt;meta&lt;/field&gt;
&lt;/object&gt;
&lt;object model="orm.layer_version" pk="3"&gt;
&lt;field rel="ManyToOneRel" to="orm.layer" name="layer"&gt;1&lt;/field&gt;
&lt;field type="IntegerField" name="layer_source"&gt;0&lt;/field&gt;
&lt;field rel="ManyToOneRel" to="orm.release" name="release"&gt;3&lt;/field&gt;
&lt;field type="CharField" name="branch"&gt;master&lt;/field&gt;
&lt;field type="CharField" name="dirpath"&gt;meta&lt;/field&gt;
&lt;/object&gt;
</literallayout>
The layer "pk" values above must be unique, and typically start at "1".
The layer version "pk" values must also be unique across all layers,
and typically start at "1".
</para>
</section>
</section>
</section>
<section id='remote-toaster-monitoring'>
<title>Remote Toaster Monitoring</title>
<para>
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
<ulink url='http://en.wikipedia.org/wiki/Representational_state_transfer'>REST</ulink>
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.
</para>
<section id='checking-health'>
<title>Checking Health</title>
<para>
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:
<literallayout class='monospaced'>
http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/health
</literallayout>
Be sure to provide values for <replaceable>host</replaceable>
and <replaceable>port</replaceable>.
If the server is alive, you will get the response HTML:
<literallayout class='monospaced'>
&lt;!DOCTYPE html&gt;
&lt;html lang="en"&gt;
&lt;head&gt;&lt;title&gt;Toaster Health&lt;/title&gt;&lt;/head&gt;
&lt;body&gt;Ok&lt;/body&gt;
&lt;/html&gt;
</literallayout>
</para>
</section>
<section id='determining-status-of-builds-in-progress'>
<title>Determining Status of Builds in Progress</title>
<para>
Sometimes it is useful to determine the status of a build
in progress.
To get the status of pending builds, use the following call:
<literallayout class='monospaced'>
http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/toastergui/api/building
</literallayout>
Be sure to provide values for <replaceable>host</replaceable>
and <replaceable>port</replaceable>.
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:
<literallayout class='monospaced'>
{"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"
}]
}
</literallayout>
The JSON data for this query is returned in a single line.
In the previous example the line has been artificially split for readability.
</para>
</section>
<section id='checking-status-of-builds-completed'>
<title>Checking Status of Builds Completed</title>
<para>
Once a build is completed, you get the status when you use
the following call:
<literallayout class='monospaced'>
http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/toastergui/api/builds
</literallayout>
Be sure to provide values for <replaceable>host</replaceable>
and <replaceable>port</replaceable>.
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:
<literallayout class='monospaced'>
{"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"
}]
}
</literallayout>
The JSON data for this query is returned in a single line.
In the previous example the line has been artificially split for readability.
</para>
</section>
<section id='determining-status-of-a-specific-build'>
<title>Determining Status of a Specific Build</title>
<para>
Sometimes it is useful to determine the status of a specific
build.
To get the status of a specific build, use the following
call:
<literallayout class='monospaced'>
http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/toastergui/api/build/<replaceable>ID</replaceable>
</literallayout>
Be sure to provide values for <replaceable>host</replaceable>,
<replaceable>port</replaceable>, and <replaceable>ID</replaceable>.
You can find the value for <replaceable>ID</replaceable> from the
Builds Completed query. See the
"<link linkend='checking-status-of-builds-completed'>Checking Status of Builds Completed</link>"
section for more information.
</para>
<para>
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:
<literallayout class='monospaced'>
{"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"
}
}
</literallayout>
The JSON data for this query is returned in a single line.
In the previous example the line has been artificially split for readability.
</para>
</section>
</section>
<section id='toaster-useful-commands'>
<title>Useful Commands</title>
<para>
In addition to the web user interface and the scripts that start
and stop Toaster, command-line commands exist through the
<filename>manage.py</filename> management script.
You can find general documentation on
<filename>manage.py</filename> at the
<ulink url='https://docs.djangoproject.com/en/1.7/topics/settings/'>Django</ulink>
site.
However, several <filename>manage.py</filename> 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
<ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
(e.g. <filename>poky</filename>) at
<filename>bitbake/lib/manage.py</filename>.
This section documents those commands.
<note><title>Notes</title>
<itemizedlist>
<listitem><para>
When using <filename>manage.py</filename> commands given
a default configuration, you must be sure that your
working directory is set to the
<ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
Using <filename>manage.py</filename> commands from the
Build Directory allows Toaster to find the
<filename>toaster.sqlite</filename> file, which is located
in the Build Directory.
</para></listitem>
<listitem><para>
For non-default database configurations, it is possible
that you can use <filename>manage.py</filename> commands
from a directory other than the Build Directory.
To do so, the
<filename>toastermain/settings.py</filename> file must be
configured to point to the correct database backend.
</para></listitem>
</itemizedlist>
</note>
</para>
<section id='toaster-command-buildslist'>
<title><filename>buildslist</filename></title>
<para>
The <filename>buildslist</filename> command lists all builds
that Toaster has recorded.
Access the command as follows:
<literallayout class='monospaced'>
$ bitbake/lib/toaster/manage.py buildslist
</literallayout>
The command returns a list, which includes numeric
identifications, of the builds that Toaster has recorded in the
current database.
</para>
<para>
You need to run the <filename>buildslist</filename> command
first to identify existing builds in the database before
using the
<link linkend='toaster-command-builddelete'><filename>builddelete</filename></link>
command.
Here is an example that assumes default repository and build
directory names:
<literallayout class='monospaced'>
$ cd ~/poky/build
$ python ../bitbake/lib/toaster/manage.py buildslist
</literallayout>
If your Toaster database had only one build, the above
<filename>buildslist</filename> command would return something
like the following:
<literallayout class='monospaced'>
1: qemux86 poky core-image-minimal
</literallayout>
</para>
</section>
<section id='toaster-command-builddelete'>
<title><filename>builddelete</filename></title>
<para>
The <filename>builddelete</filename> command deletes data
associated with a build.
Access the command as follows:
<literallayout class='monospaced'>
$ bitbake/lib/toaster/manage.py builddelete <replaceable>build_id</replaceable>
</literallayout>
The command deletes all the build data for the specified
<replaceable>build_id</replaceable>.
This command is useful for removing old and unused data from
the database.
</para>
<para>
Prior to running the <filename>builddelete</filename>
command, you need to get the ID associated with builds
by using the
<link linkend='toaster-command-buildslist'><filename>buildslist</filename></link>
command.
</para>
</section>
<section id='toaster-command-perf'>
<title><filename>perf</filename></title>
<para>
The <filename>perf</filename> command measures Toaster
performance.
Access the command as follows:
<literallayout class='monospaced'>
$ bitbake/lib/toaster/manage.py perf
</literallayout>
The command is a sanity check that returns page loading
times in order to identify performance problems.
</para>
</section>
<section id='toaster-command-checksettings'>
<title><filename>checksettings</filename></title>
<para>
The <filename>checksettings</filename> command verifies
existing Toaster settings.
Access the command as follows:
<literallayout class='monospaced'>
$ bitbake/lib/toaster/manage.py checksettings
</literallayout>
Toaster uses settings that are based on the
database to configure the building tasks.
The <filename>checksettings</filename> command verifies that
the database settings are valid in the sense that they have
the minimal information needed to start a build.
</para>
<para>
In order for the <filename>checksettings</filename> 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:
<literallayout class='monospaced'>
$ bitbake/lib/toaster/mana​ge.py syncdb
$ bitbake/lib/toaster/mana​ge.py migrate orm
$ bitbake/lib/toaster/mana​ge.py migrate bldcontrol
</literallayout>
After running these commands, you can run the
<filename>checksettings</filename> command.
</para>
</section>
<section id='toaster-command-runbuilds'>
<title><filename>runbuilds</filename></title>
<para>
The <filename>runbuilds</filename> command launches
scheduled builds.
Access the command as follows:
<literallayout class='monospaced'>
$ bitbake/lib/toaster/manage.py runbuilds
</literallayout>
The <filename>runbuilds</filename> 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.
</para>
</section>
</section>
</chapter>