path: root/documentation/toaster-manual/toaster-manual-reference.xml

<!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; ] >

<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 Metadata 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_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
                    and
                    "<ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>Using the Yocto Project's BSP Tools</ulink>"
                    sections in the Yocto Project Board Support Package (BSP)
                    Developer's Guide.
                </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='toaster-json-files'>
        <title>JSON Files</title>

        <para>
            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.
        </para>

<!--
        <para>
            To make it easier to initially start Toaster, you can import a
            pre-defined configuration file using the
            <link linkend='toaster-command-loadconf'><filename>loadconf</filename></link>
            command.
            <note>
                The configuration file is a JSON-formatted text file with
                specific fields that Toaster recognizes.
                It is not a data dump from the database, so it cannot be
                loaded directly in the database.
            </note>
        </para>
-->

        <para>
            By convention, the supplied configuration files are named
            <filename>toasterconf.json</filename>.
            The Toaster Administrator can customize the file prior to loading
            it into Toaster.
            The <filename>TOASTER_CONF</filename> variable in the
            Toaster startup script at <filename>bitbake/bin/toaster</filename>
            specifies the location of the <filename>toasterconf.json</filename> file.
        </para>

        <section id='json-file-choices'>
            <title>Configuration File Choices</title>

            <para>
                Two versions of the configuration file exist:
                <itemizedlist>
                    <listitem><para>
                        The
                        <filename>meta-poky/conf/toasterconf.json</filename>
                        in the <filename>conf</filename> directory of the
                        Yocto Project's <filename>meta-poky</filename> 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
                        <filename>poky</filename> repository (i.e.
                        <filename>&YOCTO_GIT_URL;/poky</filename>).
                        </para></listitem>
                    <listitem><para>
                        The <filename>meta/conf/toasterconf.json</filename>
                        in the <filename>conf</filename> directory of the
                        OpenEmbedded's <filename>openembedded-core</filename>
                        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
                        <filename>openembedded-core</filename> repository (i.e.
                        <filename>git://git.openembedded.org/openembedded-core</filename>).
                        </para></listitem>
                </itemizedlist>
            </para>
        </section>

        <section id='json-structure'>
            <title>File Structure</title>

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

            <section id='json-config-area'>
                <title>Configuration Area</title>

                <para>
                    This area of the JSON file sets which variables are exposed
                    to users through the Toaster web interface.
                    Users can easily edit these variables.
                </para>

                <para>
                    The variables you set here are displayed in the
                    "Configuration variables" page in Toaster.
                    Minimally, you should set the
                    <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
                    variable, which appears to users as part of the project
                    page in Toaster.
                </para>

                <para>
                    Here is the default <filename>config</filename> area:
                    <literallayout class='monospaced'>
     "config": {
         "MACHINE"      : "qemux86",
         "DISTRO"       : "poky",
         "IMAGE_FSTYPES": "ext3 jffs2 tar.bz2",
         "IMAGE_INSTALL_append": "",
         "PACKAGE_CLASSES": "package_rpm",
     },
                    </literallayout>
                </para>
            </section>

            <section id='json-layersources-area'>
                <title>Layer Sources Area</title>

                <para>
                    This area of the JSON file defines the
                    <link linkend='layer-source'>layer sources</link>
                    Toaster uses.
                    Toaster reads layer information from layer sources.
                    Three types of layer sources exist that Toaster
                    recognizes: Local, LayerIndex, and Imported.
                </para>

                <para>
                    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.
                    <note>
                        If you are setting up a hosted version of Toaster,
                        it does not make sense to have a local layer source.
                    </note>
                </para>

                <para>
                    The LayerIndex layer source uses a REST API exposed by
                    instances of the Layer Index application (e.g the public
                    <ulink url='http://layers.openembedded.org/'></ulink>)
                    to read layer data.
                </para>

                <para>
                    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.
                </para>

                <para>
                    Here is the default <filename>layersources</filename> area:
                    <literallayout class='monospaced'>
    "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"]

        }
    ],
                    </literallayout>
                </para>
            </section>

            <section id='json-bitbake-area'>
                <title>BitBake Area</title>

                <para>
                    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.
                    <note>
                        HEAD is a special option that builds whatever is
                        available on disk, without checking out any remote
                        Git repositories.
                    </note>
                </para>

                <para>
                    Here is the default <filename>bitbake</filename> area:
                    <literallayout class='monospaced'>
     "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"
         }
     ],
                    </literallayout>
                </para>
            </section>

            <section id='json-default-area'>
                <title>Default Area</title>

                <para>
                    This area of the JSON file establishes a default
                    release used by Toaster.
                    As shipped, Toaster uses the "master" release.
                </para>

                <para>
                    Here is the statement in the JSON file that establishes
                    the default release:
                    <literallayout class='monospaced'>
     "defaultrelease": "master",
                    </literallayout>
                </para>
            </section>

            <section id='json-releases-area'>
                <title>Releases Area</title>

                <para>
                    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
                    "<link linkend='toaster-releases-supported'>Pre-Configured Releases</link>"
                    section.
                </para>

                <para>
                    Here is the default <filename>releases</filename> area:
                    <literallayout class='monospaced'>
     "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 &lt;a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/\"&gt;Yocto Project master branch&lt;/a&gt;, 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 &lt;a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=jethro\"&gt;Yocto Project 2.0 \"Jethro\"&lt;/a&gt; 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 &lt;a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=fido\"&gt;Yocto Project 1.8 \"Fido\"&lt;/a&gt; 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."
         }
     ]
                    </literallayout>
                </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>
                In the previous example, the actual output appears in a single line.
                Here, however, the line has been artificially split for readability.
            </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>
            </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>
            </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>
            </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_DEV_URL;#source-directory'>Source Directory</ulink>
            (e.g. <filename>poky</filename>) at
            <filename>bitbake/lib/manage.py</filename>.
            This section documents those commands.
            <note>
                <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>

                <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>
            </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>