forked from brl/citadel
836 lines
39 KiB
XML
836 lines
39 KiB
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'>
|
|||
|
|
<?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>
|
|||
|
|
<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/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>
|