1053 lines
48 KiB
XML
1053 lines
48 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='select-the-toasterconf-json-file'>
|
||
<title>Use the <filename>toasterconf.json</filename> File</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:
|
||
<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>
|
||
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.
|
||
</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>
|
||
</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 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>.
|
||
</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 id='toaster-releases-comprised-of'>
|
||
<title>What Makes Up a Release?</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.
|
||
</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.
|
||
</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>
|
||
</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.
|
||
</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>
|
||
</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:
|
||
<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."
|
||
}
|
||
]
|
||
</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>
|
||
|
||
<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 <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>
|
||
</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_DEV_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-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>
|
||
|
||
<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>
|