Revert "poky: subtree update:b23aa6b753..ad30a6d470"
This reverts commit af5e4ef732faedf66c6dc1756432e9de2ac72988.
This commit introduced openbmc/openbmc#3720 and no solution has been
forthcoming. Revert until we can get to the bottom of this.
Change-Id: I2fb0d81eb26cf3dadb2f2abdd1a1bb7a95eaf03c
diff --git a/poky/documentation/toaster-manual/toaster-manual-reference.xml b/poky/documentation/toaster-manual/toaster-manual-reference.xml
new file mode 100644
index 0000000..ae267f4
--- /dev/null
+++ b/poky/documentation/toaster-manual/toaster-manual-reference.xml
@@ -0,0 +1,837 @@
+<!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'>
+ <?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>
+ </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'>
+ <object model="orm.toastersetting" pk="99">
+ <field type="CharField" name="name">CUSTOM_XML_ONLY</field>
+ <field type="CharField" name="value">True</field>
+ </object>
+ </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'>
+ <!-- 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>
+ </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'>
+ <!-- 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>
+ </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'>
+ <!-- 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>
+ </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'>
+ <!-- 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>
+ </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'>
+ <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>
+ </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'>
+ <!DOCTYPE html>
+ <html lang="en">
+ <head><title>Toaster Health</title></head>
+ <body>Ok</body>
+ </html>
+ </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/manage.py syncdb
+ $ bitbake/lib/toaster/manage.py migrate orm
+ $ bitbake/lib/toaster/manage.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>