Yocto 2.4
Move OpenBMC to Yocto 2.4(rocko)
Tested: Built and verified Witherspoon and Palmetto images
Change-Id: I12057b18610d6fb0e6903c60213690301e9b0c67
Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>
diff --git a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-reference.xml b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-reference.xml
index 3a46b61..e984391 100644
--- a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-reference.xml
+++ b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-reference.xml
@@ -148,177 +148,46 @@
</para>
</section>
- <section id='select-the-toasterconf-json-file'>
- <title>Use the <filename>toasterconf.json</filename> File</title>
+ <section id='use-the-fixture-feature'>
+ <title>Use the Fixture Feature</title>
<para>
- If you do not want to use the Administration
- Interface, you can edit the
- <link linkend='toaster-json-files'><filename>toasterconf.json</filename></link>
- file and reload it to Toaster.
- </para>
-
- <para>
- The Toaster startup script in
- <filename>/bitbake/bin/toaster</filename> specifies
- the location of a Toaster configuration file
- <filename>toasterconf.json</filename> as the value of
- the <filename>TOASTER_CONF</filename> variable.
- This configuration file is used to set up the initial
- configuration values within the Toaster database
- including the layer sources.
- Two versions of the configuration file exist:
- <itemizedlist>
- <listitem><para>
- The first version of the file is found in the
- <filename>conf</filename> directory of the
- <filename>meta-poky</filename> layer
- (i.e.
- <filename>meta-poky/conf/toasterconf.json</filename>).
- This version contains the default Yocto Project
- configuration for Toaster.
- </para></listitem>
- <listitem><para>
- The second version of the file is in the
- <filename>conf</filename> directory of the
- <filename>openembedded-core</filename> layer
- (i.e. <filename>meta/conf/toasterconf.json</filename>).
- This version contains the default OpenEmbedded
- configuration for Toaster.
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='edit-the-configuration-file'>
- <title>Edit the Configuration File</title>
-
- <para>
- Edit the version of the
- <filename>toasterconf.json</filename> file you
- used to set up your Toaster instance.
- In the file, you will find a section for layer sources
- such as the following:
+ 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'>
- "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"]
-
- }
- ],
+ <?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>
- You should add your own layer source to this section by
- following the same format used for the "OpenEmbedded"
- layer source shown above.
- </para>
-
- <para>
- Give your layer source a name, provide the URL of your
- layer source API, use the source type "layerindex", and
- indicate which branches from your layer source you want
- to make available through Toaster.
- For example, the OpenEmbedded layer source makes
- available only its "master", "fido", and "jethro"
- branches.
- </para>
-
- <para>
- The branches must match the branch you
- set when configuring your releases.
- For example, if you configure one release in Toaster
- by setting its branch to "branch-one" and you configure
- another release in Toaster by setting its branch to
- "branch-two", the branches in your layer source should
- be "branch-one" and "branch-two" as well.
- Doing so creates a connection between the releases
- and the layer information from your layer source.
- Thus, when users create a project with a given
- release, they will see the appropriate layers from
- your layer source.
- This connection ensures that only layers that are
- compatible with the selected project release can be
- selected for building.
- </para>
-
- <para>
- Once you have added this information to the
- <filename>toasterconf.json</filename> file, save your
- changes.
- </para>
-
- <para>
- In a terminal window, navigate to the directory that
- contains the Toaster database, which by default is the
- root of the Yocto Project
- <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
- Once you are located in that directory, run the
- "<filename>loadconf</filename>" command, which takes as
- an argument the full path to the
- <filename>toasterconf.json</filename> file you just edited.
- For example, if you cloned the
- <filename>poky</filename> repository and you edited the
- <filename>meta-poky/conf/toasterconf.json</filename> file,
- you would type something like the following:
- <literallayout class='monospaced'>
- $ bitbake/lib/toaster/manage.py loadconf /home/scottrif/poky/meta-poky/conf/toasterconf.json
- </literallayout>
- After entering this command, you need to update the
- Toaster database with the information coming from your
- new layer source.
- To do that, you should run the
- "<filename>lsupdates</filename>" command from the directory
- that contains the Toaster database.
- Here is an example:
- <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.
+ 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.
+ 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>
@@ -359,19 +228,12 @@
As shipped, Toaster is configured to work with the following
releases:
<itemizedlist>
- <listitem><para><emphasis>Yocto Project 2.0 "Jethro" or OpenEmbedded "Jethro":</emphasis>
- This release causes your Toaster projects to
- build against the head of the jethro branch at
- <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/?h=jethro'></ulink>
- or
- <ulink url='http://git.openembedded.org/openembedded-core/commit/?h=jethro'></ulink>.
- </para></listitem>
- <listitem><para><emphasis>Yocto Project 1.8 "Fido" or OpenEmbedded "Fido":</emphasis>
- This release causes your Toaster projects to
- build against the head of the fido branch at
- <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/?h=fido'></ulink>
- or
- <ulink url='http://git.openembedded.org/openembedded-core/commit/?h=fido'></ulink>.
+ <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
@@ -390,468 +252,413 @@
</itemizedlist>
</para>
</section>
+ </section>
- <section id='toaster-releases-comprised-of'>
- <title>What Makes Up a Release?</title>
+ <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>
- A release consists of the following:
- <itemizedlist>
- <listitem><para><emphasis>Name:</emphasis>
- The name of the release (<filename>name</filename>).
- This release name never appears in the the Toaster
- web interface.
- Consequently, a user never sees the release name.
+ 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><emphasis>Description:</emphasis>
- The textual description of the release
- (<filename>description</filename>).
- This description is what users encounter when creating
- projects with the Toaster web interface.
- When you configure your release, be sure to use
- a description that sufficiently describes and is
- understandable.
- If Toaster has more than one release configured, the
- release descriptions appear listed in a drop down menu
- when a user creates a new project.
- If Toaster has only one release configured, all
- projects created using the web interface take that
- release and the drop down menu does not display in the
- Toaster web interface.
+ <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><emphasis>BitBake:</emphasis>
- The Bitbake version (<filename>bitbake</filename>)
- used to build layers set in the current release.
- This version is described by a name, a Git URL, a
- branch in the Git URL, and a directory path in the
- Git repository.
- As an example, consider the following snippet from
- a Toaster JSON configuration file.
- This BitBake version uses the master branch from the
- OpenEmbedded repository:
- <literallayout class='monospaced'>
- "bitbake" : [
- {
- "name": "master",
- "giturl": "git://git.openembedded.org/bitbake",
- "branch": "master",
- "dirpath": ""
- }
- ]
- </literallayout>
- Here is more detail on each of the items that comprise
- the BitBake version:
- <itemizedlist>
- <listitem><para><emphasis>Name:</emphasis>
- A string
- (<filename>name</filename>) used to refer to
- the version of BitBake you are using with
- Toaster.
- This name is never exposed through Toaster.
- </para></listitem>
- <listitem><para><emphasis>Git URL:</emphasis>
- The URL (<filename>giturl</filename>)
- for the BitBake Git repository cloned
- for Toaster projects.
- </para></listitem>
- <listitem><para><emphasis>Branch:</emphasis>
- The Git branch, or revision,
- (<filename>branch</filename>) of the BitBake
- repository used with Toaster.
- </para></listitem>
- <listitem><para><emphasis>Directory Path:</emphasis>
- The sub-directory of the BitBake repository
- (<filename>dirpath</filename>).
- If the Git URL includes more than one
- repository, you need to set this directory.
- If the URL does not include more than a single
- repository, you can set
- <filename>dirpath</filename> to a null string
- (i.e. "").
- </para></listitem>
- </itemizedlist>
+ <listitem><para>
+ If the <filename>orm/fixtures/custom.xml</filename> file
+ exists, then its values are added.
</para></listitem>
- <listitem><para><emphasis>Branch:</emphasis>
- The branch for the layer source
- (<filename>branch</filename>) used with the release.
- For example, for the OpenEmbedded layer source, the
- "master", "fido", and "jethro" branches are available.
+ <listitem><para>
+ The layer index is then scanned and added to the database.
</para></listitem>
- <listitem><para><emphasis>Default Layers:</emphasis>
- The set of default layers
- (<filename>defaultlayers</filename>) automatically
- added to the project configuration when a project is
- created.
- </para></listitem>
- <listitem><para><emphasis>Layer Source Priorities</emphasis>
- A specification of
- <link linkend='layer-source'>layer source</link>
- priorities (<filename>layersourcepriority</filename>).
- In order for Toaster to work as intended, the
- "Imported layers" layer source should have the highest
- priority, which means that layers manually imported by
- users with the "Import layer" functionality will
- always be visible and available for selection.
- </para></listitem>
- <listitem><para><emphasis>Help Text:</emphasis>
- Help text (<filename>helptext</filename>) that explains
- what the release does when selected.
- This help text appears below the release drop-down
- menu when you create a Toaster project.
- The help text should assist users in making the correct
- decision regarding the release to use for a given
- project.
- </para></listitem>
- </itemizedlist>
+ </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>
- To summarize what comprises a release, consider the following
- example from a Toaster JSON file.
- The configuration names the release "master" and uses the
- "master" branch provided by the layer source of type
- "layerindex", which is called "OpenEmbedded", and sets
- the <filename>openembedded-core</filename> layer as the one
- to be added by default to any projects created in Toaster.
- The BitBake version used would be defined as shown earlier
- in the previous list:
+ 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'>
- "releases": [
- {
- "name": "master",
- "description": "OpenEmbedded master",
- "bitbake": "master",
- "branch": "master",
- "defaultlayers": [ "openembedded-core" ],
- "layersourcepriority": { "Imported layers": 99, "Local OpenEmbedded" : 10, "OpenEmbedded" : 0 },
- "helptext": "Toaster will run your builds using the tip of the <a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/\">Yocto Project master branch</a>, where active development takes place. This is not a stable branch, so your builds might not work as expected."
- }
- ]
+ <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>
- <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>
+ <section id='understanding-fixture-file-format'>
+ <title>Understanding Fixture File Format</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>
+ 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='json-structure'>
- <title>File Structure</title>
+ <section id='determining-status-of-builds-in-progress'>
+ <title>Determining Status of Builds in Progress</title>
<para>
- The <filename>toasterconf.json</filename> file consists of
- easily readable areas: configuration, layer sources, BitBake,
- default release, and releases.
+ 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>
- <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"]
-
+ <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 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 <a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/\">Yocto Project master branch</a>, where active development takes place. This is not a stable branch, so your builds might not work as expected."
- },
- {
- "name": "jethro",
- "description": "Yocto Project 2.0 Jethro",
- "bitbake": "jethro",
- "branch": "jethro",
- "defaultlayers": [ "openembedded-core", "meta-poky", "meta-yocto-bsp"],
- "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 },
- "helptext": "Toaster will run your builds with the tip of the <a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=jethro\">Yocto Project 2.0 \"Jethro\"</a> branch."
- },
- {
- "name": "fido",
- "description": "Yocto Project 1.8 Fido",
- "bitbake": "fido",
- "branch": "fido",
- "defaultlayers": [ "openembedded-core", "meta-poky", "meta-yocto-bsp"],
- "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 },
- "helptext": "Toaster will run your builds with the tip of the <a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=fido\">Yocto Project 1.8 \"Fido\"</a> branch."
- },
- {
- "name": "local",
- "description": "Local Yocto Project",
- "bitbake": "HEAD",
- "branch": "HEAD",
- "defaultlayers": [ "openembedded-core", "meta-poky", "meta-yocto-bsp"],
- "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 },
- "helptext": "Toaster will run your builds with the version of the Yocto Project you have cloned or downloaded to your computer."
- }
- ]
- </literallayout>
- </para>
- </section>
+ }
+ </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>
@@ -870,7 +677,7 @@
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>
+ <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.
@@ -879,7 +686,7 @@
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_DEV_URL;#build-directory'>Build Directory</ulink>.
+ <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
@@ -1005,30 +812,6 @@
</para>
</section>
- <section id='toaster-command-loadconf'>
- <title><filename>loadconf</filename></title>
-
- <para>
- The <filename>loadconf</filename> command loads an
- existing Toaster configuration file (JSON file).
- You must run this on a new database that does not have any
- data.
- Running this command on an existing database that has data
- results in errors.
- Access the command as follows:
- <literallayout class='monospaced'>
- $ bitbake/lib/toaster/manage.py loadconf <replaceable>filepath</replaceable>
- </literallayout>
- The <filename>loadconf</filename> command configures a database
- based on the supplied existing
- <filename>toasterconf.json</filename> file.
- For information on the <filename>toasterconf.json</filename>,
- see the
- "<link linkend='toaster-json-files'>JSON Files</link>"
- section.
- </para>
- </section>
-
<section id='toaster-command-runbuilds'>
<title><filename>runbuilds</filename></title>