Squashed 'yocto-poky/' content from commit ea562de
git-subtree-dir: yocto-poky
git-subtree-split: ea562de57590c966cd5a75fda8defecd397e6436
diff --git a/documentation/toaster-manual/figures/hosted-service.png b/documentation/toaster-manual/figures/hosted-service.png
new file mode 100644
index 0000000..01fea7b
--- /dev/null
+++ b/documentation/toaster-manual/figures/hosted-service.png
Binary files differ
diff --git a/documentation/toaster-manual/figures/simple-configuration.png b/documentation/toaster-manual/figures/simple-configuration.png
new file mode 100644
index 0000000..e8fce2b
--- /dev/null
+++ b/documentation/toaster-manual/figures/simple-configuration.png
Binary files differ
diff --git a/documentation/toaster-manual/figures/toaster-title.png b/documentation/toaster-manual/figures/toaster-title.png
new file mode 100644
index 0000000..b7ea39c
--- /dev/null
+++ b/documentation/toaster-manual/figures/toaster-title.png
Binary files differ
diff --git a/documentation/toaster-manual/toaster-manual-customization.xsl b/documentation/toaster-manual/toaster-manual-customization.xsl
new file mode 100644
index 0000000..d78694a
--- /dev/null
+++ b/documentation/toaster-manual/toaster-manual-customization.xsl
@@ -0,0 +1,28 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
+
+ <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
+
+<!--
+
+ <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
+
+ <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" />
+
+-->
+
+ <xsl:include href="../template/permalinks.xsl"/>
+ <xsl:include href="../template/section.title.xsl"/>
+ <xsl:include href="../template/component.title.xsl"/>
+ <xsl:include href="../template/division.title.xsl"/>
+ <xsl:include href="../template/formal.object.heading.xsl"/>
+ <xsl:include href="../template/embedded_video.xsl"/>
+
+ <xsl:param name="html.stylesheet" select="'toaster-manual-style.css'" />
+ <xsl:param name="chapter.autolabel" select="1" />
+ <xsl:param name="appendix.autolabel" select="A" />
+ <xsl:param name="section.autolabel" select="1" />
+ <xsl:param name="section.label.includes.component.label" select="1" />
+ <xsl:param name="generate.id.attributes" select="1" />
+
+</xsl:stylesheet>
diff --git a/documentation/toaster-manual/toaster-manual-intro.xml b/documentation/toaster-manual/toaster-manual-intro.xml
new file mode 100644
index 0000000..ad9e08b
--- /dev/null
+++ b/documentation/toaster-manual/toaster-manual-intro.xml
@@ -0,0 +1,172 @@
+<!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-intro'>
+<title>Introduction</title>
+
+ <para>
+ Toaster is a web interface to the Yocto Project's
+ <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.
+ The interface enables you to configure and run your builds.
+ Information about builds is collected and stored in a database.
+ You can use Toaster to configure and start builds on multiple
+ remote build servers.
+ </para>
+
+ <note>
+ <para>
+ This release of Toaster does allow you to configure and initiate
+ builds.
+ However, you cannot use Toaster to customize image recipes, which
+ still must either be done by hand or through
+ <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>.
+ As Toaster matures, it eventually will equal and surpass Hob
+ functionality, at which time Hob will be deprecated.
+ </para>
+
+ <para>
+ For more information on Hob,
+ see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#image-development-using-hob'>Image Development Using Hob</ulink>"
+ section in the Yocto Project Development Manual.
+ </para>
+ </note>
+
+ <section id='intro-modes'>
+ <title>Toaster Operational Modes</title>
+
+ <para>
+ You can use Toaster in Analysis Mode or Build Mode:
+ <itemizedlist>
+ <listitem><para><emphasis>Analysis Mode:</emphasis>
+ In Analysis Mode, you can record builds and statistics.
+ In this Mode, you directly access the
+ <filename>bitbake</filename> command, which you then use to
+ build images.</para>
+ <para>Analysis Mode requires you to have first started
+ Toaster and then to initiate your build using the
+ <filename>bitbake</filename> command from the shell.
+ Toaster must be started before the build or it will not
+ collect build data.</para>
+ <para>Toaster has the following capabilities in
+ Analysis Mode:
+ <itemizedlist>
+ <listitem><para>
+ See what was built (recipes and packages) and what
+ packages were installed into your final image.
+ </para></listitem>
+ <listitem><para>
+ Browse the directory structure of your image.
+ </para></listitem>
+ <listitem><para>
+ See the value of all variables in your build
+ configuration, and which files set each value.
+ </para></listitem>
+ <listitem><para>
+ Examine error, warning and trace messages to aid
+ in debugging.
+ </para></listitem>
+ <listitem><para>
+ See information about the BitBake tasks executed
+ and reused during your build, including those that
+ used shared state.
+ </para></listitem>
+ <listitem><para>
+ See dependency relationships between recipes,
+ packages and tasks
+ </para></listitem>
+ <listitem><para>
+ See performance information such as build time,
+ task time, CPU usage, and disk I/O.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para><emphasis>Build Mode:</emphasis>
+ In Build Mode, Toaster handles the build configuration,
+ scheduling and execution.
+ In this mode, all your interaction with the build system
+ happens through the web interface.
+ You do not have direct access to the
+ <filename>bitbake</filename> command.</para>
+ <para>Using this mode, you configure and start your builds
+ within Toaster's GUI.
+ Each project can be configured for a specific version
+ of the build system.
+ As shipped, Toaster supports Yocto Project Releases 1.7 and
+ beyond.</para>
+ <para>Toaster has all the same capabilities in Build Mode
+ as it does in Analysis Mode plus the following:
+ <itemizedlist>
+ <listitem><para>
+ Browse layers listed in the various
+ <link linkend='layer-source'>layer sources</link>
+ that are available in your project (e.g. the
+ OpenEmbedded Metadata Index at
+ <ulink url='http://layers.openembedded.org/layerindex/'></ulink>).
+ </para></listitem>
+ <listitem><para>
+ Import your own layers for building.
+ </para></listitem>
+ <listitem><para>
+ Add and remove layers from your configuration.
+ </para></listitem>
+ <listitem><para>
+ Set configuration variables.
+ </para></listitem>
+ <listitem><para>
+ Select a target or multiple targets to build.
+ </para></listitem>
+ <listitem><para>
+ Start your builds.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='toaster-installation-options'>
+ <title>Installation Options</title>
+
+ <para>
+ You can set Toaster up to run as a local instance or as a shared
+ hosted service.
+ Regardless of how you set up Toaster, both Analysis and Build
+ Modes are available.
+ </para>
+
+ <para>
+ When Toaster is set up as a local instance, all the components
+ reside on a single build host.
+ Fundamentally, a local instance of Toaster is suited for a single
+ user developing on a single build host.
+ </para>
+
+ <para>
+ <imagedata fileref="figures/simple-configuration.png" align="center" width="6in" depth="1.5in" />
+ </para>
+
+ <para>
+ Toaster as a hosted service is suited for multiple users
+ developing across several build hosts.
+ When Toaster is set up as a hosted service, its components can
+ be spread across several machines:
+ </para>
+
+ <para>
+ <imagedata fileref="figures/hosted-service.png" align="center" width="6in" depth="3.5in" />
+ </para>
+ </section>
+
+<!--THIS EXTRA INFORMATION PROBABLY WILL GO AWAY
+ For additional information on installing and running Toaster, see the
+ "<ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Installation_and_Running'>Installation and Running</ulink>"
+ section of the "Toaster" wiki page.
+ For complete information on the API and its search operation
+ URI, parameters, and responses, see the
+ <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink>
+ Wiki page.
+ </para>
+-->
+</chapter>
diff --git a/documentation/toaster-manual/toaster-manual-reference.xml b/documentation/toaster-manual/toaster-manual-reference.xml
new file mode 100644
index 0000000..0c9401f
--- /dev/null
+++ b/documentation/toaster-manual/toaster-manual-reference.xml
@@ -0,0 +1,1078 @@
+<!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>
+ When you set up Toaster in Build Mode, you are prompted
+ to select a Toaster configuration file.
+ This configuration file is used to set up the initial
+ configuration values within the Toaster database
+ including the layer sources.
+ Three 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-yocto</filename> layer
+ (i.e.
+ <filename>meta-yocto/conf/toasterconf.json</filename>).
+ 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 had cloned the
+ <filename>poky</filename> repository (i.e.
+ <filename>git://git.yoctoproject.org/poky</filename>).
+ </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.
+ 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>
+ <listitem><para>
+ The third version is a sample configuration
+ useful for when you want to set up a hosted
+ service in Build Mode.
+ You can find this version on the
+ <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>File:Toasterconf.json.txt.patch</ulink>
+ wiki page.
+ </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", "master", "fido", "dizzy"],
+ "layers": [
+ {
+ "name": "openembedded-core",
+ "local_path": "meta",
+ "vcs_url": "remote:origin",
+ "dirpath": "meta"
+ },
+ {
+ "name": "meta-yocto",
+ "local_path": "meta-yocto",
+ "vcs_url": "remote:origin",
+ "dirpath": "meta-yocto"
+ },
+ {
+ "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", "fido", "dizzy"]
+ },
+ {
+ "name": "Imported layers",
+ "sourcetype": "imported",
+ "apiurl": "",
+ "branches": ["master", "fido", "dizzy", "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 "dizzy"
+ 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-yocto/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-yocto/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 1.7 "Dizzy" or OpenEmbedded "Dizzy":</emphasis>
+ This release causes your Toaster projects to
+ build against the head of the dizzy branch at
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/?h=dizzy'></ulink>
+ or
+ <ulink url='http://git.openembedded.org/openembedded-core/commit/?h=dizzy'></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 "dizzy" 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 OpenEmbedded master branch, 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>
+ If you are going to be using Toaster in Build Mode, it must
+ be initially configured before use.
+ 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.
+ When you set up Toaster locally to run in Build Mode, the system
+ startup script actively looks for compatible configuration files
+ and prompts you to select a file to load if it detects that the
+ database has not been configured.
+ </para>
+
+ <section id='json-file-choices'>
+ <title>Configuration File Choices</title>
+
+ <para>
+ Three versions of the configuration file exist:
+ <itemizedlist>
+ <listitem><para>
+ The
+ <filename>meta-yocto/conf/toasterconf.json</filename>
+ in the <filename>conf</filename> directory of the
+ Yocto Project's <filename>meta-yocto</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>
+ <listitem><para>
+ The <filename>Toasterconf.json.txt.patch</filename>
+ located on the
+ <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>File:Toasterconf.json.txt.patch</ulink>
+ wiki page.
+ This version of the file is useful as a sample
+ configuration for when you want to set up Toaster as a
+ hosted service in Build Mode.
+ </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",
+ "SDKMACHINE" : "x86_64"
+ },
+ </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", "master", "fido", "dizzy"],
+ "layers": [
+ {
+ "name": "openembedded-core",
+ "local_path": "meta",
+ "vcs_url": "remote:origin",
+ "dirpath": "meta"
+ },
+ {
+ "name": "meta-yocto",
+ "local_path": "meta-yocto",
+ "vcs_url": "remote:origin",
+ "dirpath": "meta-yocto"
+ },
+ {
+ "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", "fido", "dizzy"]
+ },
+ {
+ "name": "Imported layers",
+ "sourcetype": "imported",
+ "apiurl": "",
+ "branches": ["master", "fido", "dizzy", "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, dizzy, 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": "fido",
+ "giturl": "remote:origin",
+ "branch": "fido",
+ "dirpath": "bitbake"
+ },
+ {
+ "name": "dizzy",
+ "giturl": "remote:origin",
+ "branch": "dizzy",
+ "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-yocto", "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": "fido",
+ "description": "Yocto Project 1.8 Fido",
+ "bitbake": "fido",
+ "branch": "fido",
+ "defaultlayers": [ "openembedded-core", "meta-yocto", "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": "dizzy",
+ "description": "Yocto Project 1.7 Dizzy",
+ "bitbake": "dizzy",
+ "branch": "dizzy",
+ "defaultlayers": [ "openembedded-core", "meta-yocto", "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=dizzy\">Yocto Project 1.7 \"Dizzy\"</a> branch."
+ },
+ {
+ "name": "local",
+ "description": "Local Yocto Project",
+ "bitbake": "HEAD",
+ "branch": "HEAD",
+ "defaultlayers": [ "openembedded-core", "meta-yocto", "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>
+ In Build Mode, 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>
diff --git a/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
new file mode 100644
index 0000000..869d249
--- /dev/null
+++ b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
@@ -0,0 +1,1024 @@
+<!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-setup-and-use'>
+
+<title>Setting Up and Using Toaster</title>
+
+ <section id='using-toaster-in-analysis-mode'>
+ <title>Using Toaster in Analysis Mode</title>
+
+ <para>
+ This section describes how to use Toaster in Analysis Mode
+ after setting Toaster up as a local instance or as a hosted
+ service.
+ </para>
+
+ <section id='setting-up-locally-and-running-in-analysis-mode'>
+ <title>Setting Up Locally and Running in Analysis Mode</title>
+
+ <para>
+ Follow these steps to set up a local instance of Toaster and
+ then run in Analysis Mode:
+ <orderedlist>
+ <listitem><para><emphasis>Prepare your Build System:</emphasis>
+ Be sure your system has the Toaster requirements
+ by following the steps in the
+ "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>"
+ section.
+ </para></listitem>
+ <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis>
+ Get the requirements set up so that you can use the
+ Yocto Project to build images.
+ See the
+ "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
+ section in the Yocto Project Quick Start for information.
+ </para></listitem>
+ <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis>
+ From your
+ <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+ (e.g. <filename>poky/build</filename>), source the build
+ environment setup script
+ <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink>
+ or
+ <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>.
+ </para></listitem>
+ <listitem><para><emphasis>Start Toaster:</emphasis>
+ From the
+ <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
+ start Toaster:
+ <literallayout class='monospaced'>
+ $ source toaster start
+ </literallayout>
+ </para></listitem>
+ <listitem><para><emphasis>Start Your Build Using BitBake:</emphasis>
+ Use the <filename>bitbake</filename> command to start your
+ build.
+ Here is an example that builds the
+ <filename>core-image-minimal</filename> image:
+ <literallayout class='monospaced'>
+ $ bitbake core-image-minimal
+ </literallayout>
+ </para></listitem>
+ <listitem><para><emphasis>Open Your Browser:</emphasis>
+ Open your browser and visit
+ <filename>http://host:port/toastergui</filename>.
+ For host and port values, see the output of the
+ <filename>source toaster start</filename> command.
+ For information on how to use Toaster, see the
+ "<link linkend='using-the-toaster-web-interface'>Using the Toaster Web Interface</link>"
+ section.
+ </para></listitem>
+ </orderedlist>
+ </para>
+
+ <para>
+
+ </para>
+ </section>
+
+ <section id='setting-up-a-hosted-service-and-running-in-analysis-mode'>
+ <title>Setting Up a Hosted Service and Running in Analysis Mode</title>
+
+ <para>
+ A hosted service resides on a shared server and allows
+ multiple users to take advantage of Toaster.
+ </para>
+
+ <para>
+ In a production environment, you might want to have multiple
+ local instances of the Toaster Logging Interface running on
+ various remote build machines, and have those local instances
+ access and use a single web server.
+ To do this, you need to do the following:
+ <itemizedlist>
+ <listitem><para>
+ Maintain a common SQL database.
+ </para></listitem>
+ <listitem><para>
+ Set up separate instances of BitBake servers
+ and Toaster Logging Interfaces for each of those
+ separate BitBake servers.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ The common SQL database allows the Web server to show data from
+ all the various BitBake builds.
+ Setting the SQL database outside of any
+ <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+ maintains a separation between the various builds.
+ The BitBake servers, the SQL server, and the Web server or
+ servers can be run on separate machines.
+ </para>
+
+ <para>
+ Follow these steps to set up and run a hosted service and run
+ Toaster in Analysis Mode:
+ <note>
+ The steps assume a Toaster installation path of
+ <filename>/opt/bitbake/</filename>.
+ </note>
+ <orderedlist>
+ <listitem><para><emphasis>Prepare your Build System:</emphasis>
+ Be sure your system has the Toaster requirements
+ by following the steps in the
+ "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>"
+ section.
+ </para></listitem>
+ <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis>
+ Get the requirements set up so that you can use the
+ Yocto Project to build images.
+ See the
+ "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
+ section in the Yocto Project Quick Start for information.
+ </para></listitem>
+ <listitem><para><emphasis>Install and Set up the Database Server:</emphasis>
+ You can use any SQL server out of the box.
+ It is recommended that you use
+ <filename>mysql-server</filename> because it has
+ the advantages of advanced SQL features along with a
+ fast and reliable database.
+ However, setting up <filename>mysql-server</filename>
+ is more complex and might require a Database
+ Administrator to tune it.</para>
+ <para>Another supported database backend is
+ <filename>sqlite3</filename>.
+ With <filename>sqlite3</filename>, you have the
+ advantage of no configuration and an easy installation.
+ However, Toaster still requires direct access to the
+ backend.
+ The <filename>sqlite</filename> backend is also slower
+ as compared to <filename>mysql-server</filename>, and
+ has no transactional support.</para>
+ <para>You should set up proper username and password
+ access on the shared database for everyone that will
+ be using Toaster.
+ You need administrator rights for the root account,
+ which is not the same thing as root access on the
+ machine.
+ Here is an example that installs
+ <filename>mysql-server</filename> and sets up
+ some user accounts and the database.
+ <literallayout class='monospaced'>
+ $ apt-get install mysql-server
+ $ mysql -u root
+ mysql> CREATE USER 'newuser'@'localhost' IDENTIFIED BY 'password';
+ mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost';
+ mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost';
+ mysql> CREATE DATABASE 'toaster';
+ </literallayout>
+ You need a separate clone of the
+ <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>
+ for the Database Server.
+ This clone is only used for getting the latest Toaster
+ files.
+ You can set this up using the following Git command.
+ Be sure to set up the directory outside of any
+ Build Directories.
+ <literallayout class='monospaced'>
+ $ git clone git://git.yoctoproject.org/poky
+ </literallayout>
+ In the separately cloned tree for the Database Server,
+ edit the
+ <filename>bitbake/lib/toaster/toastermain/settings.py</filename>
+ file so that the <filename>DATABASES</filename> value
+ points to the previously created database server.
+ Use the username and password established
+ earlier.
+ Here is an example:
+ <literallayout class='monospaced'>
+ $ cat /opt/bitbake/lib/toaster/toastermain/settings.py
+ ...
+ DATABASES = {
+ 'default': {
+ 'ENGINE': 'django.db.backends.mysql',
+ 'NAME': 'toaster',
+ 'USER': 'newuser',
+ 'PASSWORD': 'password',
+ 'HOST': '192.168.0.25',
+ 'PORT': '3306',
+ }
+ ...
+ </literallayout>
+ </para></listitem>
+ <listitem><para><emphasis>Install and Set Up the Web Server:</emphasis>
+ For a production environment, it is recommended that
+ you install and set up a front-end web server.
+ This server allows for load balancing and
+ multi-threading over Toaster and
+ <ulink url='https://docs.djangoproject.com/en/1.7/howto/deployment/wsgi/'><filename>django</filename> WSGI</ulink>.
+ Here is an example that uses Apache web server.
+ <literallayout class='monospaced'>
+ $ apt-get install apache2 libapache2-mod-wsgi
+ $ a2enmod wsgi
+ $ cat /etc/apache2/sites-available/000-default.conf
+
+ ...
+
+ # the WSGIPythonPath is global
+ WSGIPythonPath /opt/bitbake/lib/toaster/
+
+ ...
+
+ #snip - in VirtualHost
+ WSGIScriptAlias / /opt/bitbake/lib/toaster/toastermain/wsgi.py
+
+ <Directory //opt/bitbake/lib/toaster/toastermain/>
+ <Files wsgi.py>
+ Require all granted
+ </Files>
+ </Directory>
+
+ ...
+ </literallayout>
+ You need to collect static media from Toaster and
+ continue configuring Apache to serve that static
+ media:
+ <literallayout class='monospaced'>
+ $ mkdir /var/www.html/static && cd /var/www.html/static
+ $ /opt/bitbake/lib/toaster/manage.py collectstatic
+ $ cat /etc/apache2/sites-available/000-default.conf
+
+ ...
+
+ # in VirtualHost, AHEAD of the WSGIScriptAlias definition
+ Alias /static/ /var/www.html/static/
+
+ <Directory /var/www.html/static/>
+ Require all granted
+ </Directory>
+
+ ...
+
+ WSGIScript Alias / /opt/bitbake/lib/toaster/toastermain/wsgi.py
+
+ ...
+ </literallayout>
+ </para></listitem>
+ <listitem><para><emphasis>Start Toaster:</emphasis>
+ Synchronize the databases for toaster, and then start
+ up the web server.
+ Here is an example that continues with the assumed
+ components from the previous steps:
+ <literallayout class='monospaced'>
+ $ /opt/bitbake/lib/toaster/manage.py syncdb
+ $ /opt/bitbake/lib/toaster/manage.py migrate orm
+ $ /opt/bitbake/lib/toaster/manage.py migrate bldcontrol
+
+ $ service apache2 restart
+ </literallayout>
+ You can find general documentation on
+ <filename>manage.py</filename> at the
+ <ulink url='https://docs.djangoproject.com/en/1.7/ref/django-admin/'>Django</ulink>
+ site.
+ For reference information on Toaster-specific
+ <filename>manage.py</filename> commands,
+ see the
+ "<link linkend='toaster-useful-commands'>Useful Commands</link>"
+ section.
+ </para></listitem>
+ <listitem><para><emphasis>Enable Build Logging to the Common SQL Server for Each Build Directory you are Using:</emphasis>
+ You need to make sure that the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-toaster'><filename>toaster</filename></ulink>
+ class and build history are enabled.
+ This is done in a
+ <filename>toaster.conf</filename> file that is
+ created automatically by the toaster
+ <filename>start</filename> command,
+ and that lives inside the
+ <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+ in <filename>/conf/toaster.conf</filename>.</para>
+ <para>That file should include the following line:
+ <literallayout class='monospaced'>
+ INHERIT += "toaster buildhistory"
+ </literallayout>
+ For information on build history, see the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
+ section in the Yocto Project Development
+ Manual.</para>
+ <para>You also need to point to the database that you set
+ up in step 3.
+ You can do this by exporting the <filename>DATABASE_URL</filename>
+ variable as follows:
+ <literallayout class='monospaced'>
+ export DATABASE_URL=mysql://newuser:password@192.168.0.25:3306/toaster
+ </literallayout>
+ This example assumes that you are using
+ <filename>mysql-server</filename>.
+ The IP address should be the IP address of your
+ database server.
+ </para></listitem>
+ <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis>
+ From your
+ <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+ on each of the build systems,
+ (e.g. <filename>poky/build</filename>), source the
+ build environment setup script (i.e.
+ <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink>
+ or
+ <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>).
+ </para></listitem>
+ <listitem><para><emphasis>Start the BitBake Server:</emphasis>
+ Start the BitBake server using the following command:
+ <literallayout class='monospaced'>
+ $ bitbake --postread conf/toaster.conf --server-only -t xmlrpc -B localhost:0 && export BBSERVER=localhost:-1
+ </literallayout>
+ </para></listitem>
+ <listitem><para><emphasis>Start the Logging Server:</emphasis>
+ Start the Toaster Logging Interface using the following
+ command:
+ <literallayout class='monospaced'>
+ $ nohup bitbake --observe-only -u toasterui >toaster_ui.log &
+ </literallayout>
+ <note>
+ No hard-coded ports are used in the BitBake options
+ as there is enough code to run
+ <filename>autodiscovery</filename> for BitBake
+ ports.
+ Doing so prevents collisions.
+ </note>
+ </para></listitem>
+ <listitem><para><emphasis>Start Builds Using BitBake:</emphasis>
+ Use the <filename>bitbake</filename> command to start a
+ build on a build system.
+ Here is an example that builds the
+ <filename>core-image-minimal</filename> image:
+ <literallayout class='monospaced'>
+ $ bitbake core-image-minimal
+ </literallayout>
+ When you are finished with a build in a given
+ Build Directory, be sure to <filename>kill</filename>
+ the BitBake server for that build area:
+ <literallayout class='monospaced'>
+ $ bitbake -m
+ </literallayout>
+ </para></listitem>
+ </orderedlist>
+ </para>
+
+ <para>
+ For information on how to use the Toaster web interface,
+ see the
+ "<link linkend='using-the-toaster-web-interface'>Using the Toaster Web Interface</link>"
+ section.
+ </para>
+ </section>
+ </section>
+
+ <section id='using-toaster-in-build-mode'>
+ <title>Using Toaster in Build Mode</title>
+
+ <para>
+ This section describes how to use Toaster in Build Mode
+ after setting Toaster up as a local instance or as a hosted
+ service.
+ </para>
+
+ <section id='setting-up-locally-and-running-in-build-mode'>
+ <title>Setting Up Locally and Running in Build Mode</title>
+
+ <para>
+ Follow these steps to set up a local instance of Toaster and
+ then run in Build Mode:
+ <orderedlist>
+ <listitem><para><emphasis>Prepare your Build System:</emphasis>
+ Be sure your system has the Toaster requirements
+ by following the steps in the
+ "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>"
+ section.
+ </para></listitem>
+ <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis>
+ Get the requirements set up so that you can use the
+ Yocto Project to build images.
+ See the
+ "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
+ section in the Yocto Project Quick Start for information.
+ </para></listitem>
+ <listitem><para><emphasis>Start Toaster:</emphasis>
+ From the root of the source directory (e.g
+ <filename>poky/</filename>), run the following command:
+ <literallayout class='monospaced'>
+ $ bitbake/bin/toaster
+ </literallayout>
+ </para></listitem>
+ <listitem><para><emphasis>Create a Superuser:</emphasis>
+ Django will ask you if you want to create a superuser.
+ You can skip this step, but it is recommended that you
+ create a superuser.
+ You can use the superuser to access the Django
+ administration interface and make changes to the
+ Toaster configuration.
+ </para></listitem>
+ <listitem><para><emphasis>Select the Build Log Directory:</emphasis>
+ Toaster asks you to specify the directory where you
+ want to store the build log files.
+ Choosing a directory for these files makes sure they
+ are always available to you.
+ If you do not choose a directory, the logs can
+ disappear (e.g. deleting the Build Directory).</para>
+ <para>When Toaster prompts you for the Build Log
+ directory, you can select the suggested default
+ or provide a path to a different directory.
+ </para></listitem>
+ <listitem><para><emphasis>Specify the Layer Checkout Directory:</emphasis>
+ Toaster asks you to specify the directory into which
+ layers are checked out.
+ Toaster clones any layers needed for your builds
+ inside this directory.</para>
+ <para>When Toaster prompts you for the Layer
+ checkout directory, you can select the suggested
+ default or provide a path to a different directory.
+ </para></listitem>
+ <listitem><para><emphasis>Specify the Build Directory Path:</emphasis>
+ Toaster asks you to specify the path to the
+ Build Directory.
+ You can select the suggested default or provide a
+ path to a different directory.
+ </para></listitem>
+ <listitem><para><emphasis>Choose Whether or not to Import a Default Toaster Configuration File:</emphasis>
+ Toaster asks you if you want to import a default
+ Toaster configuration file.
+ Toaster configurations are stored in
+ JSON files called
+ <filename>toasterconf.json</filename>.
+ For information on JSON files, see the
+ "<link linkend='toaster-json-files'>JSON Files</link>"
+ section.</para>
+ <para>You can skip importing a configuration file
+ by entering "0" at the prompt.
+ However, it is recommended that you import one of the
+ configuration files listed during this step.
+ You can always amend the imported configuration during
+ a later stage through the Django administration
+ interface.</para>
+ <para>For general information on Django, see the
+ available
+ <ulink url='https://docs.djangoproject.com/en/1.7/'>documentation</ulink>.
+ You can also find information on Toaster-specific
+ <filename>manage.py</filename> commands in the
+ "<link linkend='toaster-useful-commands'>Useful Commands</link>"
+ section.
+ </para></listitem>
+ <listitem><para><emphasis>Open the Browser:</emphasis>
+ If no browser window appears, open your favorite
+ browser and enter the following:
+ <literallayout class='monospaced'>
+ http://localhost:8000/toastergui
+ </literallayout>
+ You can now use the Toaster web interface.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='setting-up-a-hosted-service-and-running-in-build-mode'>
+ <title>Setting Up a Hosted Service and Running in Build Mode</title>
+
+ <para>
+ Follow these steps to set up a hosted service and run Toaster
+ in Build Mode:
+ <orderedlist>
+ <listitem><para><emphasis>Prepare your Build System:</emphasis>
+ Be sure your system has the Toaster requirements
+ by following the steps in the
+ "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>"
+ section.
+ </para></listitem>
+ <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis>
+ Get the requirements set up so that you can use the
+ Yocto Project to build images.
+ See the
+ "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
+ section in the Yocto Project Quick Start for information.
+ </para></listitem>
+ <listitem><para><emphasis>Be Sure Management is Enabled:</emphasis>
+ If you are running Toaster under Apache, you need to
+ be sure management is enabled.
+ To enable management, set
+ <filename>MANAGED</filename> to "True" by adding
+ the following to the
+ <filename>bitbake/lib/toaster/settings.py</filename>
+ file:
+ <literallayout class='monospaced'>
+ MANAGED="True"
+ </literallayout>
+ </para></listitem>
+ <listitem><para><emphasis>Set Up Toaster for Normal Usage:</emphasis>
+ You need to configure each build environment, layer
+ sources, and BitBake versions.</para>
+ <para>Verify that your releases have been loaded correctly by
+ using the Toaster web interface to create a new
+ project.
+ Check the "Releases" dropdown menu to be sure your
+ newly specified releases exist.</para>
+ <para>If you want to use the administration interface
+ for this step, here is a set of example commands
+ with some descriptions as an example:
+ <literallayout class='monospaced'>
+ # Create the user under which the builds will run
+ $ adduser poky
+
+ # Bring up the administration interface
+ $xdg-open http://<replaceable>server-address</replaceable>/admin/
+
+ # Login with the admin user previously created
+
+ # Go to the BuildEnvironment object in Build Environments and
+ # set address to local host, sourcedir to /home/poky, and
+ # builddir to /home/pokybuild.
+ #
+ # Save your changes and exit
+
+ # Go to Home, Layer Sources and select add Layer Source
+ # Name: OpenEmbedded, Sourcetype: layerindex,
+ # Apiurl: http://layers openembedded.org/layerindex/api/
+ # Save your changes and exit
+
+ # Go to Home, Bitbake Versions, Add bitbake version;
+ # Take version information from: http://git.openembedded.org/bitbake/refs/heads,
+ # This example assumes "master" version.
+ # set Name: master, Giturl git://git.openembedded.org/bitbake
+ # branch master, dirpath /
+ # Save your changes and exit
+ </literallayout>
+ You also need to configure the project releases, the
+ default variables, and update information from the
+ layer index.
+ Continuing with the example:
+ <literallayout class='monospaced'>
+ # Go to Home, Releases, Add release
+ # set Name: master, Description: Current master release, select Bitbake Version,
+ # and Branch: master
+ # Save your changes and exit
+
+ # Go to Home, Toaster Settings, select the Setting for DEFAULT_RELEASE
+ # set Helptext: This selects the default release., Value: master
+ # Save your changes and exit
+
+ # Go to Home, Bitbake Versions, Add bitbake version;
+ # take version information from : http://git.openembedded.org/bitbake/refs/heads,
+ # this manual assumes the master version
+ # set Name: master, Giturl git://git.openembedded.org/bitbake
+ # branch master, dirpath /
+ # Save your changes and exit
+
+ # Update the information
+ # bitbake/lib/toaster/manage.py lsupdates
+ </literallayout>
+ For reference information on Toaster-specific
+ <filename>manage.py</filename> commands, see the
+ "<link linkend='toaster-useful-commands'>Useful Commands</link>"
+ section.
+ </para></listitem>
+ <listitem><para><emphasis>Install and Set up the Database Server:</emphasis>
+ You can use any SQL server out of the box.
+ It is recommended that you use
+ <filename>mysql-server</filename> because it has
+ the advantages of advanced SQL features along with a
+ fast and reliable database.
+ However, setting up <filename>mysql-server</filename>
+ is more complex and might require a Database
+ Administrator to tune it.</para>
+ <para>Another supported database backend is
+ <filename>sqlite3</filename>.
+ With <filename>sqlite3</filename>, you have the
+ advantage of no configuration and an easy installation.
+ However, Toaster still requires direct access to the
+ backend.
+ The <filename>sqlite</filename> backend is also slower
+ as compared to <filename>mysql-server</filename>, and
+ has no transactional support.</para>
+ <para>You should set up proper username and password
+ access on the shared database for everyone that will
+ be using Toaster.
+ You need administrator rights for the root account,
+ which is not the same thing as root access on the
+ machine.
+ Here is an example that installs
+ <filename>mysql-server</filename> and sets up
+ some user accounts and the database.
+ <literallayout class='monospaced'>
+ $ apt-get install mysql-server
+ $ mysql -u root
+ mysql> CREATE USER 'newuser'@'localhost' IDENTIFIED BY 'password';
+ mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost';
+ mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost';
+ mysql> CREATE DATABASE 'toaster';
+ </literallayout>
+ You need a separate clone of the
+ <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>
+ for the Database Server.
+ This clone is only used for getting the latest Toaster
+ files.
+ You can set this up using the following Git command.
+ Be sure to set up the directory outside of any
+ Build Directories.
+ <literallayout class='monospaced'>
+ $ git clone git://git.yoctoproject.org/poky
+ </literallayout>
+ In the separately cloned tree for the Database Server,
+ edit the
+ <filename>bitbake/lib/toaster/toastermain/settings.py</filename>
+ file so that the <filename>DATABASES</filename> value
+ points to the previously created database server.
+ Use the username and password established
+ earlier.
+ Here is an example:
+ <literallayout class='monospaced'>
+ $ cat /opt/bitbake/lib/toaster/toastermain/settings.py
+ ...
+ DATABASES = {
+ 'default': {
+ 'ENGINE': 'django.db.backends.mysql',
+ 'NAME': 'toaster',
+ 'USER': 'newuser',
+ 'PASSWORD': 'password',
+ 'HOST': '192.168.0.25',
+ 'PORT': '3306',
+ }
+ ...
+ </literallayout>
+ </para></listitem>
+ <listitem><para><emphasis>Create the Database</emphasis>
+ Use the following commands to create the default
+ database structure:
+ <literallayout class='monospaced'>
+ $ bitbake/lib/toaster/manage.py syncdb
+ $ bitbake/lib/toaster/manage.py migrate orm
+ $ bitbake/lib/toaster/manage.py migrate bldcontrol
+ </literallayout>
+ The interface asks you if you want to create a
+ superuser.
+ Do not skip this step.
+ You will use the superuser account to access the
+ administration interface and make changes to the
+ Toaster configuration.
+ </para></listitem>
+ <listitem><para><emphasis>Select Where the Build Process Takes Place:</emphasis>
+ You need to create three directories for storing
+ build artifacts, downloading sources, and running
+ builds.
+ All three directories need to be writable by
+ the user, which is "poky" in this example.
+ The build artifacts directory needs to readable by the
+ apache user.
+ You also need free disk space in the range of
+ 100 Gbytes.
+ Following are three suggested directories:
+ <literallayout class='monospaced'>
+ /home/poky/buildartifacts/
+ /home/poky/build/
+ /home/poky/sources/
+ </literallayout>
+ </para></listitem>
+ <listitem><para><emphasis>Set Up the <filename>toasterconf.json</filename> File:</emphasis>
+ <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>Download the hosted <filename>toasterconf.json</filename> file</ulink>
+ from the Yocto Project wiki and edit it to suit your
+ environment.
+ For information on the relevant sections of the file,
+ see the
+ "<link linkend='toaster-json-files'>JSON Files</link>"
+ section.</para>
+ <para>After editing the file, load it by running
+ the following:
+ <literallayout class='monospaced'>
+ $ bitbake/lib/toaster/manage.py loadconf path-to-toasterconf.json-file
+ </literallayout>
+ For reference information on Toaster-specific
+ <filename>manage.py</filename>, see the
+ "<link linkend='toaster-useful-commands'>Useful Commands</link>"
+ section.
+ </para></listitem>
+ <listitem><para><emphasis>Check the Toaster Settings:</emphasis>
+ Configure the build environment by running the
+ following:
+ <literallayout class='monospaced'>
+ $ bitbake/lib/toaster/manage.py checksettings
+ </literallayout>
+ When prompted, paste in the directory paths created
+ previously during Step 7.
+ For reference information on Toaster-specific
+ <filename>manage.py</filename>, see the
+ "<link linkend='toaster-useful-commands'>Useful Commands</link>"
+ section.
+ </para></listitem>
+ <listitem><para><emphasis>Install and Set Up the Web Server:</emphasis>
+ For a production environment, it is recommended that
+ you install and set up a front-end web server.
+ This server allows for load balancing and
+ multi-threading over Toaster and
+ <ulink url='https://docs.djangoproject.com/en/1.7/howto/deployment/wsgi/'><filename>django</filename> WSGI</ulink>.
+ Here is an example that uses Apache web server:
+ <literallayout class='monospaced'>
+ $ apt-get install apache2 libapache2-mod-wsgi
+ $ a2enmod wsgi
+ $ cat /etc/apache2/sites-available/000-default.conf
+
+ ...
+
+ # the WSGIPythonPath is global
+ WSGIPythonPath /opt/bitbake/lib/toaster/
+
+ ...
+
+ #snip - in VirtualHost
+ WSGIScriptAlias / /opt/bitbake/lib/toaster/toastermain/wsgi.py
+
+ <Directory //opt/bitbake/lib/toaster/toastermain/>
+ <Files wsgi.py>
+ Require all granted
+ </Files>
+ </Directory>
+
+ ...
+ </literallayout>
+ You need to collect static media from Toaster and
+ continue configuring Apache to serve that static
+ media:
+ <literallayout class='monospaced'>
+ $ mkdir /var/www.html/static && cd /var/www.html/static
+ $ /opt bitbake/lib/toaster/manage.py collectstatic
+ $ cat /etc/apache2/sites-available/000-default.conf
+
+ ...
+
+ # in VirtualHost, AHEAD of the WSGIScriptAlias definition
+ Alias /static/ /var/www.html/static/
+
+ <Directory /var/www.html/static/>
+ Require all granted
+ </Directory>
+
+ ...
+
+ WSGIScript Alias / /opt/bitbake/lib/toaster/toastermain/wsgi.py
+
+ ...
+ </literallayout>
+ </para></listitem>
+ <listitem><para><emphasis>Start Toaster:</emphasis>
+ Synchronize the databases for Toaster, and then start
+ up the web server.
+ Here is an example that continues with the assumed
+ components from the previous steps:
+ <literallayout class='monospaced'>
+ $ /opt/bitbake/lib/toaster/manage.py syncdb
+ $ /opt/bitbake/lib/toaster/manage.py migrate orm
+ $ /opt/bitbake/lib/toaster/manage.py migrate bldcontrol
+
+ $ service apache2 restart
+ </literallayout>
+ For reference information on the
+ <filename>manage.py</filename> commands used here,
+ see the
+ "<link linkend='toaster-useful-commands'>Useful Commands</link>"
+ section.
+ </para></listitem>
+ <listitem><para><emphasis>Set up Build Control and Open the Web Interface:</emphasis>
+ You need to run the build control manager.
+ You can do this as shown in the following example:
+ <literallayout class='monospaced'>
+ # as the "poky" user, start the runbuilds command in a loop (or put it in crontab!)
+ $ sudo -i -u poky
+ $ while true; do /opt/bitbake/lib/toaster/manage.py runbuilds; sleep 10; done
+
+ # open up the web interface
+ $ xdg-open http://[server-address]/toastergui/
+ </literallayout>
+ It is suggested that you enable build control by
+ setting <filename>runbuilds</filename> in the
+ <filename>crontab</filename> as follows:
+ <literallayout class='monospaced'>
+ $ crontab -l
+ * * * * * /opt/bitbake/lit/toaster/manage.py runbuilds
+ </literallayout>
+ </para></listitem>
+ <listitem><para><emphasis>Open the Browser:</emphasis>
+ Once the Apache server is running, connect to it with
+ your favorite browser and verify that the Toaster
+ interface comes up:
+ <literallayout class='monospaced'>
+ http://localhost:8000/toastergui
+ </literallayout>
+ You can track accesses and errors in the Apache
+ service logs.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+ </section>
+
+ <section id='using-the-toaster-web-interface'>
+ <title>Using the Toaster Web Interface</title>
+
+ <para>
+ The Toaster web interface allows you to do the following:
+ <itemizedlist>
+ <listitem><para>
+ Browse published layers in the
+ <ulink url='http://layers.openembedded.org'>OpenEmbedded Metadata Index</ulink>
+ that are available for your selected version of the build
+ system.
+ </para></listitem>
+ <listitem><para>
+ Import your own layers for building.
+ </para></listitem>
+ <listitem><para>
+ Add and remove layers from your configuration.
+ </para></listitem>
+ <listitem><para>
+ Set configuration variables.
+ </para></listitem>
+ <listitem><para>
+ Select a target or multiple targets to build.
+ </para></listitem>
+ <listitem><para>
+ Start your builds.
+ </para></listitem>
+ <listitem><para>
+ See what was built (recipes and packages) and what
+ packages were installed into your final image.
+ </para></listitem>
+ <listitem><para>
+ Browse the directory structure of your image.
+ </para></listitem>
+ <listitem><para>
+ See the value of all variables in your build configuration,
+ and which files set each value.
+ </para></listitem>
+ <listitem><para>
+ Examine error, warning and trace messages to aid in
+ debugging.
+ </para></listitem>
+ <listitem><para>
+ See information about the BitBake tasks executed and
+ reused during your build, including those that used
+ shared state.
+ </para></listitem>
+ <listitem><para>
+ See dependency relationships between recipes, packages
+ and tasks.
+ </para></listitem>
+ <listitem><para>
+ See performance information such as build time, task time,
+ CPU usage, and disk I/O.
+ </para></listitem>
+ </itemizedlist>
+ Following are several videos that show how to use the Toaster GUI:
+ <itemizedlist>
+ <listitem><para><emphasis>Build Configuration:</emphasis>
+ This
+ <ulink url='https://www.youtube.com/watch?v=qYgDZ8YzV6w'>video</ulink>
+ overviews and demonstrates build configuration for Toaster.
+ </para></listitem>
+ <listitem><para><emphasis>Toaster Homepage and Table Controls:</emphasis>
+ This
+ <ulink url='https://www.youtube.com/watch?v=QEARDnrR1Xw'>video</ulink>
+ goes over the Toaster entry page, and provides
+ an overview of the data manipulation capabilities of
+ Toaster, which include search, sorting and filtering by
+ different criteria.
+ </para></listitem>
+ <listitem><para><emphasis>Build Dashboard:</emphasis>
+ This
+ <ulink url='https://www.youtube.com/watch?v=KKqHYcnp2gE'>video</ulink>
+ shows you the build dashboard, a page providing an
+ overview of the information available for a selected build.
+ </para></listitem>
+ <listitem><para><emphasis>Image Information:</emphasis>
+ This
+ <ulink url='https://www.youtube.com/watch?v=XqYGFsmA0Rw'>video</ulink>
+ walks through the information Toaster provides
+ about images: packages installed and root file system.
+ </para></listitem>
+ <listitem><para><emphasis>Configuration:</emphasis>
+ This
+ <ulink url='https://www.youtube.com/watch?v=UW-j-T2TzIg'>video</ulink>
+ provides Toaster build configuration information.
+ </para></listitem>
+ <listitem><para><emphasis>Tasks:</emphasis>
+ This
+ <ulink url='https://www.youtube.com/watch?v=D4-9vGSxQtw'>video</ulink>
+ shows the information Toaster provides about the
+ tasks run by the build system.
+ </para></listitem>
+ <listitem><para><emphasis>Recipes and Packages Built:</emphasis>
+ This
+ <ulink url='https://www.youtube.com/watch?v=x-6dx4huNnw'>video</ulink>
+ shows the information Toaster provides about recipes
+ and packages built.
+ </para></listitem>
+ <listitem><para><emphasis>Performance Data:</emphasis>
+ This
+ <ulink url='https://www.youtube.com/watch?v=qWGMrJoqusQ'>video</ulink>
+ shows the build performance data provided by
+ Toaster.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+<!--
+ <section id='toaster-gui-vids-1'>
+ <title>Toaster Homepage and Table Controls</title>
+
+ <para>
+ This video goes over the Toaster entry page, and provides
+ an overview of the data manipulation capabilities of Toaster,
+ which include search, sorting and filtering by different
+ criteria.
+ <mediaobject>
+ <videoobject>
+ <videodata width="640" height="480" fileref="http://www.youtube.com/v/QEARDnrR1Xw"></videodata>
+ </videoobject>
+ </mediaobject>
+ </para>
+ </section>
+
+ <section id='toaster-gui-vids-2'>
+ <title>Build Dashboard</title>
+
+ <para>
+ This video shows you the build dashboard, a page providing an
+ overview of the information available for a selected build.
+ <mediaobject>
+ <videoobject>
+ <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/KKqHYcnp2gE"></videodata>
+ </videoobject>
+ </mediaobject>
+ </para>
+ </section>
+
+ <section id='toaster-gui-vids-3'>
+ <title>Image Information</title>
+
+ <para>
+ This video walks through the information Toaster provides
+ about images: packages installed and root file system.
+ <mediaobject>
+ <videoobject>
+ <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/XqYGFsmA0Rw"></videodata>
+ </videoobject>
+ </mediaobject>
+ </para>
+ </section>
+
+ <section id='toaster-gui-vids-4'>
+ <title>Configuration</title>
+
+ <para>
+ This video shows the information Toaster provides about build
+ configuration.
+ <mediaobject>
+ <videoobject>
+ <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/UW-j-T2TzIg"></videodata>
+ </videoobject>
+ </mediaobject>
+ </para>
+ </section>
+
+ <section id='toaster-gui-vids-5'>
+ <title>Tasks</title>
+
+ <para>
+ This video shows the information Toaster provides about the
+ tasks run by the build system.
+ <mediaobject>
+ <videoobject>
+ <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/D4-9vGSxQtw"></videodata>
+ </videoobject>
+ </mediaobject>
+ </para>
+ </section>
+
+ <section id='toaster-gui-vids-6'>
+ <title>Recipes and Packages Built</title>
+
+ <para>
+ This video shows the information Toaster provides about recipes
+ and packages built.
+ <mediaobject>
+ <videoobject>
+ <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/x-6dx4huNnw"></videodata>
+ </videoobject>
+ </mediaobject>qYgDZ8YzV6w
+ </para>
+ </section>
+ <section id='toaster-gui-vids-7'>
+ <title>Performance Data</title>
+
+ <para>
+ This video shows the build performance data provided by
+ Toaster.
+ <mediaobject>
+ <videoobject>
+ <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/qWGMrJoqusQ"></videodata>
+ </videoobject>
+ </mediaobject>
+ </para>
+ </section>
+-->
+</chapter>
diff --git a/documentation/toaster-manual/toaster-manual-start.xml b/documentation/toaster-manual/toaster-manual-start.xml
new file mode 100644
index 0000000..fbdb5ec
--- /dev/null
+++ b/documentation/toaster-manual/toaster-manual-start.xml
@@ -0,0 +1,141 @@
+<!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-start'>
+
+<title>Preparing to Use Toaster</title>
+
+ <para>
+ This chapter describes how you need to prepare your system in order to
+ use Toaster.
+ </para>
+
+ <section id='toaster-setting-up-the-basic-system-requirements'>
+ <title>Setting Up the Basic System Requirements</title>
+
+ <para>
+ You first need to be sure your build system is set up to run
+ the Yocto Project.
+ See the
+ "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
+ section in the Yocto Project Quick Start for information on how
+ to set up your system for the Yocto Project.
+ </para>
+ </section>
+
+ <section id='toaster-establishing-toaster-system-dependencies'>
+ <title>Establishing Toaster System Dependencies</title>
+
+ <para>
+ Toaster requires extra Python dependencies in order to run.
+ A Toaster requirements file named
+ <filename>toaster-requirements.txt</filename> defines the
+ Python dependencies.
+ The requirements file is located in the
+ <filename>bitbake</filename> directory, which is located in the
+ root directory of the
+ <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+ (e.g. <filename>poky/bitbake/toaster-requirements.txt</filename>).
+ The dependencies appear in a <filename>pip</filename>,
+ install-compatible format.
+ </para>
+
+ <section id='toaster-optional-virtual-environment'>
+ <title>Optionally Setting Up a Python Virtual Environment</title>
+
+ <para>
+ It is highly recommended that you use a Python virtual
+ environment that allows you to maintain a dedicated Python
+ executable and its own set of installed modules.
+ Doing so separates the executable from the Python and modules
+ provided by the operating system and therefore avoids any
+ version conflicts.
+ </para>
+
+ <para>
+ Follow these steps to set up your virtual environment.
+ These steps assume a Ubuntu distribution:
+ <orderedlist>
+ <listitem><para><emphasis>Install <filename>virtualenv</filename>:</emphasis>
+ Install the supported
+ <filename>python-virtualenv</filename> package from your
+ distribution rather than using <filename>pip</filename>.
+ <literallayout class='monospaced'>
+ $ sudo apt-get install python-virtualenv
+ </literallayout>
+ </para></listitem>
+ <listitem><para><emphasis>Create and Activate a Virtual Environment:</emphasis>
+ <literallayout class='monospaced'>
+ $ virtualenv venv
+ $ source venv/bin/activate
+ </literallayout>
+ </para></listitem>
+ </orderedlist>
+ <note>
+ If you do choose to set up a virtual environment in
+ which to run Toaster, you must initialize that
+ virtual environment each time you want to start
+ Toaster.
+ Use the following to initialize the environment just
+ before you start Toaster:
+ <literallayout class='monospaced'>
+ $ source venv/bin/activate
+ </literallayout>
+ </note>
+ </para>
+ </section>
+
+ <section id='toaster-load-packages'>
+ <title>Install Toaster Packages</title>
+
+ <para>
+ You need to install the packages that Toaster requires.
+ Use this command:
+ <literallayout class='monospaced'>
+ $ pip install -r bitbake/toaster-requirements.txt
+ </literallayout>
+ </para>
+ </section>
+
+<!-- Commenting this section out for now in case it needs to be used again.
+
+ <section id='toaster-install-daemon'>
+ <title>Install <filename>daemon</filename></title>
+
+ <para>
+ Toaster depends on
+ <ulink url='http://www.libslack.org/daemon/'><filename>daemon</filename></ulink>.
+ Depending on your distribution, how you install
+ <filename>daemon</filename> differs:
+ <itemizedlist>
+ <listitem><para><emphasis>Debian-Based Systems:</emphasis>
+ If you are running a Debian-based distribution,
+ install <filename>daemon</filename> using the
+ following command:
+ <literallayout class='monospaced'>
+ $ sudo apt-get install daemon
+ </literallayout>
+ </para></listitem>
+ <listitem><para><emphasis>Non-Debian-Based Systems:</emphasis>
+ If you are not running a Debian-based distribution
+ (Redhat-based distribution such as Fedora),
+ you need to download the file relevant to the
+ architecture and then install
+ <filename>daemon</filename> manually.
+ Following are the commands for 64-bit distributions:
+ <literallayout class='monospaced'>
+ $ wget http://libslack.org/daemon/download/daemon-0.6.4-1.x86_64.rpm
+ $ sudo rpm -i daemon-0.6.4-1.x86_64.rpm
+ </literallayout>
+ Here are the commands for a 32-bit distribution:
+ <literallayout class='monospaced'>
+ $ wget http://libslack.org/daemon/download/daemon-0.6.4-1.i686.rpm
+ $ sudo rpm -i daemon-0.6.4-1.i686.rpm
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section> -->
+ </section>
+</chapter>
diff --git a/documentation/toaster-manual/toaster-manual-style.css b/documentation/toaster-manual/toaster-manual-style.css
new file mode 100644
index 0000000..6d6b9fb
--- /dev/null
+++ b/documentation/toaster-manual/toaster-manual-style.css
@@ -0,0 +1,984 @@
+/*
+ Generic XHTML / DocBook XHTML CSS Stylesheet.
+
+ Browser wrangling and typographic design by
+ Oyvind Kolas / pippin@gimp.org
+
+ Customised for Poky by
+ Matthew Allum / mallum@o-hand.com
+
+ Thanks to:
+ Liam R. E. Quin
+ William Skaggs
+ Jakub Steiner
+
+ Structure
+ ---------
+
+ The stylesheet is divided into the following sections:
+
+ Positioning
+ Margins, paddings, width, font-size, clearing.
+ Decorations
+ Borders, style
+ Colors
+ Colors
+ Graphics
+ Graphical backgrounds
+ Nasty IE tweaks
+ Workarounds needed to make it work in internet explorer,
+ currently makes the stylesheet non validating, but up until
+ this point it is validating.
+ Mozilla extensions
+ Transparency for footer
+ Rounded corners on boxes
+
+*/
+
+
+ /*************** /
+ / Positioning /
+/ ***************/
+
+body {
+ font-family: Verdana, Sans, sans-serif;
+
+ min-width: 640px;
+ width: 80%;
+ margin: 0em auto;
+ padding: 2em 5em 5em 5em;
+ color: #333;
+}
+
+h1,h2,h3,h4,h5,h6,h7 {
+ font-family: Arial, Sans;
+ color: #00557D;
+ clear: both;
+}
+
+h1 {
+ font-size: 2em;
+ text-align: left;
+ padding: 0em 0em 0em 0em;
+ margin: 2em 0em 0em 0em;
+}
+
+h2.subtitle {
+ margin: 0.10em 0em 3.0em 0em;
+ padding: 0em 0em 0em 0em;
+ font-size: 1.8em;
+ padding-left: 20%;
+ font-weight: normal;
+ font-style: italic;
+}
+
+h2 {
+ margin: 2em 0em 0.66em 0em;
+ padding: 0.5em 0em 0em 0em;
+ font-size: 1.5em;
+ font-weight: bold;
+}
+
+h3.subtitle {
+ margin: 0em 0em 1em 0em;
+ padding: 0em 0em 0em 0em;
+ font-size: 142.14%;
+ text-align: right;
+}
+
+h3 {
+ margin: 1em 0em 0.5em 0em;
+ padding: 1em 0em 0em 0em;
+ font-size: 140%;
+ font-weight: bold;
+}
+
+h4 {
+ margin: 1em 0em 0.5em 0em;
+ padding: 1em 0em 0em 0em;
+ font-size: 120%;
+ font-weight: bold;
+}
+
+h5 {
+ margin: 1em 0em 0.5em 0em;
+ padding: 1em 0em 0em 0em;
+ font-size: 110%;
+ font-weight: bold;
+}
+
+h6 {
+ margin: 1em 0em 0em 0em;
+ padding: 1em 0em 0em 0em;
+ font-size: 110%;
+ font-weight: bold;
+}
+
+.authorgroup {
+ background-color: transparent;
+ background-repeat: no-repeat;
+ padding-top: 256px;
+ background-image: url("figures/toaster-title.png");
+ background-position: left top;
+ margin-top: -256px;
+ padding-right: 50px;
+ margin-left: 0px;
+ text-align: right;
+ width: 740px;
+}
+
+h3.author {
+ margin: 0em 0me 0em 0em;
+ padding: 0em 0em 0em 0em;
+ font-weight: normal;
+ font-size: 100%;
+ color: #333;
+ clear: both;
+}
+
+.author tt.email {
+ font-size: 66%;
+}
+
+.titlepage hr {
+ width: 0em;
+ clear: both;
+}
+
+.revhistory {
+ padding-top: 2em;
+ clear: both;
+}
+
+.toc,
+.list-of-tables,
+.list-of-examples,
+.list-of-figures {
+ padding: 1.33em 0em 2.5em 0em;
+ color: #00557D;
+}
+
+.toc p,
+.list-of-tables p,
+.list-of-figures p,
+.list-of-examples p {
+ padding: 0em 0em 0em 0em;
+ padding: 0em 0em 0.3em;
+ margin: 1.5em 0em 0em 0em;
+}
+
+.toc p b,
+.list-of-tables p b,
+.list-of-figures p b,
+.list-of-examples p b{
+ font-size: 100.0%;
+ font-weight: bold;
+}
+
+.toc dl,
+.list-of-tables dl,
+.list-of-figures dl,
+.list-of-examples dl {
+ margin: 0em 0em 0.5em 0em;
+ padding: 0em 0em 0em 0em;
+}
+
+.toc dt {
+ margin: 0em 0em 0em 0em;
+ padding: 0em 0em 0em 0em;
+}
+
+.toc dd {
+ margin: 0em 0em 0em 2.6em;
+ padding: 0em 0em 0em 0em;
+}
+
+div.glossary dl,
+div.variablelist dl {
+}
+
+.glossary dl dt,
+.variablelist dl dt,
+.variablelist dl dt span.term {
+ font-weight: normal;
+ width: 20em;
+ text-align: right;
+}
+
+.variablelist dl dt {
+ margin-top: 0.5em;
+}
+
+.glossary dl dd,
+.variablelist dl dd {
+ margin-top: -1em;
+ margin-left: 25.5em;
+}
+
+.glossary dd p,
+.variablelist dd p {
+ margin-top: 0em;
+ margin-bottom: 1em;
+}
+
+
+div.calloutlist table td {
+ padding: 0em 0em 0em 0em;
+ margin: 0em 0em 0em 0em;
+}
+
+div.calloutlist table td p {
+ margin-top: 0em;
+ margin-bottom: 1em;
+}
+
+div p.copyright {
+ text-align: left;
+}
+
+div.legalnotice p.legalnotice-title {
+ margin-bottom: 0em;
+}
+
+p {
+ line-height: 1.5em;
+ margin-top: 0em;
+
+}
+
+dl {
+ padding-top: 0em;
+}
+
+hr {
+ border: solid 1px;
+}
+
+
+.mediaobject,
+.mediaobjectco {
+ text-align: center;
+}
+
+img {
+ border: none;
+}
+
+ul {
+ padding: 0em 0em 0em 1.5em;
+}
+
+ul li {
+ padding: 0em 0em 0em 0em;
+}
+
+ul li p {
+ text-align: left;
+}
+
+table {
+ width :100%;
+}
+
+th {
+ padding: 0.25em;
+ text-align: left;
+ font-weight: normal;
+ vertical-align: top;
+}
+
+td {
+ padding: 0.25em;
+ vertical-align: top;
+}
+
+p a[id] {
+ margin: 0px;
+ padding: 0px;
+ display: inline;
+ background-image: none;
+}
+
+a {
+ text-decoration: underline;
+ color: #444;
+}
+
+pre {
+ overflow: auto;
+}
+
+a:hover {
+ text-decoration: underline;
+ /*font-weight: bold;*/
+}
+
+/* This style defines how the permalink character
+ appears by itself and when hovered over with
+ the mouse. */
+
+[alt='Permalink'] { color: #eee; }
+[alt='Permalink']:hover { color: black; }
+
+
+div.informalfigure,
+div.informalexample,
+div.informaltable,
+div.figure,
+div.table,
+div.example {
+ margin: 1em 0em;
+ padding: 1em;
+ page-break-inside: avoid;
+}
+
+
+div.informalfigure p.title b,
+div.informalexample p.title b,
+div.informaltable p.title b,
+div.figure p.title b,
+div.example p.title b,
+div.table p.title b{
+ padding-top: 0em;
+ margin-top: 0em;
+ font-size: 100%;
+ font-weight: normal;
+}
+
+.mediaobject .caption,
+.mediaobject .caption p {
+ text-align: center;
+ font-size: 80%;
+ padding-top: 0.5em;
+ padding-bottom: 0.5em;
+}
+
+.epigraph {
+ padding-left: 55%;
+ margin-bottom: 1em;
+}
+
+.epigraph p {
+ text-align: left;
+}
+
+.epigraph .quote {
+ font-style: italic;
+}
+.epigraph .attribution {
+ font-style: normal;
+ text-align: right;
+}
+
+span.application {
+ font-style: italic;
+}
+
+.programlisting {
+ font-family: monospace;
+ font-size: 80%;
+ white-space: pre;
+ margin: 1.33em 0em;
+ padding: 1.33em;
+}
+
+.tip,
+.warning,
+.caution,
+.note {
+ margin-top: 1em;
+ margin-bottom: 1em;
+
+}
+
+/* force full width of table within div */
+.tip table,
+.warning table,
+.caution table,
+.note table {
+ border: none;
+ width: 100%;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+ padding: 0.8em 0.0em 0.0em 0.0em;
+ margin : 0em 0em 0em 0em;
+}
+
+.tip p,
+.warning p,
+.caution p,
+.note p {
+ margin-top: 0.5em;
+ margin-bottom: 0.5em;
+ padding-right: 1em;
+ text-align: left;
+}
+
+.acronym {
+ text-transform: uppercase;
+}
+
+b.keycap,
+.keycap {
+ padding: 0.09em 0.3em;
+ margin: 0em;
+}
+
+.itemizedlist li {
+ clear: none;
+}
+
+.filename {
+ font-size: medium;
+ font-family: Courier, monospace;
+}
+
+
+div.navheader, div.heading{
+ position: absolute;
+ left: 0em;
+ top: 0em;
+ width: 100%;
+ background-color: #cdf;
+ width: 100%;
+}
+
+div.navfooter, div.footing{
+ position: fixed;
+ left: 0em;
+ bottom: 0em;
+ background-color: #eee;
+ width: 100%;
+}
+
+
+div.navheader td,
+div.navfooter td {
+ font-size: 66%;
+}
+
+div.navheader table th {
+ /*font-family: Georgia, Times, serif;*/
+ /*font-size: x-large;*/
+ font-size: 80%;
+}
+
+div.navheader table {
+ border-left: 0em;
+ border-right: 0em;
+ border-top: 0em;
+ width: 100%;
+}
+
+div.navfooter table {
+ border-left: 0em;
+ border-right: 0em;
+ border-bottom: 0em;
+ width: 100%;
+}
+
+div.navheader table td a,
+div.navfooter table td a {
+ color: #777;
+ text-decoration: none;
+}
+
+/* normal text in the footer */
+div.navfooter table td {
+ color: black;
+}
+
+div.navheader table td a:visited,
+div.navfooter table td a:visited {
+ color: #444;
+}
+
+
+/* links in header and footer */
+div.navheader table td a:hover,
+div.navfooter table td a:hover {
+ text-decoration: underline;
+ background-color: transparent;
+ color: #33a;
+}
+
+div.navheader hr,
+div.navfooter hr {
+ display: none;
+}
+
+
+.qandaset tr.question td p {
+ margin: 0em 0em 1em 0em;
+ padding: 0em 0em 0em 0em;
+}
+
+.qandaset tr.answer td p {
+ margin: 0em 0em 1em 0em;
+ padding: 0em 0em 0em 0em;
+}
+.answer td {
+ padding-bottom: 1.5em;
+}
+
+.emphasis {
+ font-weight: bold;
+}
+
+
+ /************* /
+ / decorations /
+/ *************/
+
+.titlepage {
+}
+
+.part .title {
+}
+
+.subtitle {
+ border: none;
+}
+
+/*
+h1 {
+ border: none;
+}
+
+h2 {
+ border-top: solid 0.2em;
+ border-bottom: solid 0.06em;
+}
+
+h3 {
+ border-top: 0em;
+ border-bottom: solid 0.06em;
+}
+
+h4 {
+ border: 0em;
+ border-bottom: solid 0.06em;
+}
+
+h5 {
+ border: 0em;
+}
+*/
+
+.programlisting {
+ border: solid 1px;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example {
+ border: 1px solid;
+}
+
+
+
+.tip,
+.warning,
+.caution,
+.note {
+ border: 1px solid;
+}
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+ border-bottom: 1px solid;
+}
+
+.question td {
+ border-top: 1px solid black;
+}
+
+.answer {
+}
+
+
+b.keycap,
+.keycap {
+ border: 1px solid;
+}
+
+
+div.navheader, div.heading{
+ border-bottom: 1px solid;
+}
+
+
+div.navfooter, div.footing{
+ border-top: 1px solid;
+}
+
+ /********* /
+ / colors /
+/ *********/
+
+body {
+ color: #333;
+ background: white;
+}
+
+a {
+ background: transparent;
+}
+
+a:hover {
+ background-color: #dedede;
+}
+
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7,
+h8 {
+ background-color: transparent;
+}
+
+hr {
+ border-color: #aaa;
+}
+
+
+.tip, .warning, .caution, .note {
+ border-color: #fff;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+ border-bottom-color: #fff;
+}
+
+
+.warning {
+ background-color: #f0f0f2;
+}
+
+.caution {
+ background-color: #f0f0f2;
+}
+
+.tip {
+ background-color: #f0f0f2;
+}
+
+.note {
+ background-color: #f0f0f2;
+}
+
+.glossary dl dt,
+.variablelist dl dt,
+.variablelist dl dt span.term {
+ color: #044;
+}
+
+div.figure,
+div.table,
+div.example,
+div.informalfigure,
+div.informaltable,
+div.informalexample {
+ border-color: #aaa;
+}
+
+pre.programlisting {
+ color: black;
+ background-color: #fff;
+ border-color: #aaa;
+ border-width: 2px;
+}
+
+.guimenu,
+.guilabel,
+.guimenuitem {
+ background-color: #eee;
+}
+
+
+b.keycap,
+.keycap {
+ background-color: #eee;
+ border-color: #999;
+}
+
+
+div.navheader {
+ border-color: black;
+}
+
+
+div.navfooter {
+ border-color: black;
+}
+
+
+ /*********** /
+ / graphics /
+/ ***********/
+
+/*
+body {
+ background-image: url("images/body_bg.jpg");
+ background-attachment: fixed;
+}
+
+.navheader,
+.note,
+.tip {
+ background-image: url("images/note_bg.jpg");
+ background-attachment: fixed;
+}
+
+.warning,
+.caution {
+ background-image: url("images/warning_bg.jpg");
+ background-attachment: fixed;
+}
+
+.figure,
+.informalfigure,
+.example,
+.informalexample,
+.table,
+.informaltable {
+ background-image: url("images/figure_bg.jpg");
+ background-attachment: fixed;
+}
+
+*/
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7{
+}
+
+/*
+Example of how to stick an image as part of the title.
+
+div.article .titlepage .title
+{
+ background-image: url("figures/white-on-black.png");
+ background-position: center;
+ background-repeat: repeat-x;
+}
+*/
+
+div.preface .titlepage .title,
+div.colophon .title,
+div.chapter .titlepage .title,
+div.article .titlepage .title
+{
+}
+
+div.section div.section .titlepage .title,
+div.sect2 .titlepage .title {
+ background: none;
+}
+
+
+h1.title {
+ background-color: transparent;
+ background-repeat: no-repeat;
+ height: 256px;
+ text-indent: -9000px;
+ overflow:hidden;
+}
+
+h2.subtitle {
+ background-color: transparent;
+ text-indent: -9000px;
+ overflow:hidden;
+ width: 0px;
+ display: none;
+}
+
+ /*************************************** /
+ / pippin.gimp.org specific alterations /
+/ ***************************************/
+
+/*
+div.heading, div.navheader {
+ color: #777;
+ font-size: 80%;
+ padding: 0;
+ margin: 0;
+ text-align: left;
+ position: absolute;
+ top: 0px;
+ left: 0px;
+ width: 100%;
+ height: 50px;
+ background: url('/gfx/heading_bg.png') transparent;
+ background-repeat: repeat-x;
+ background-attachment: fixed;
+ border: none;
+}
+
+div.heading a {
+ color: #444;
+}
+
+div.footing, div.navfooter {
+ border: none;
+ color: #ddd;
+ font-size: 80%;
+ text-align:right;
+
+ width: 100%;
+ padding-top: 10px;
+ position: absolute;
+ bottom: 0px;
+ left: 0px;
+
+ background: url('/gfx/footing_bg.png') transparent;
+}
+*/
+
+
+
+ /****************** /
+ / nasty ie tweaks /
+/ ******************/
+
+/*
+div.heading, div.navheader {
+ width:expression(document.body.clientWidth + "px");
+}
+
+div.footing, div.navfooter {
+ width:expression(document.body.clientWidth + "px");
+ margin-left:expression("-5em");
+}
+body {
+ padding:expression("4em 5em 0em 5em");
+}
+*/
+
+ /**************************************** /
+ / mozilla vendor specific css extensions /
+/ ****************************************/
+/*
+div.navfooter, div.footing{
+ -moz-opacity: 0.8em;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example,
+.tip,
+.warning,
+.caution,
+.note {
+ -moz-border-radius: 0.5em;
+}
+
+b.keycap,
+.keycap {
+ -moz-border-radius: 0.3em;
+}
+*/
+
+table tr td table tr td {
+ display: none;
+}
+
+
+hr {
+ display: none;
+}
+
+table {
+ border: 0em;
+}
+
+ .photo {
+ float: right;
+ margin-left: 1.5em;
+ margin-bottom: 1.5em;
+ margin-top: 0em;
+ max-width: 17em;
+ border: 1px solid gray;
+ padding: 3px;
+ background: white;
+}
+ .seperator {
+ padding-top: 2em;
+ clear: both;
+ }
+
+ #validators {
+ margin-top: 5em;
+ text-align: right;
+ color: #777;
+ }
+ @media print {
+ body {
+ font-size: 8pt;
+ }
+ .noprint {
+ display: none;
+ }
+ }
+
+
+.tip,
+.note {
+ background: #f0f0f2;
+ color: #333;
+ padding: 20px;
+ margin: 20px;
+}
+
+.tip h3,
+.note h3 {
+ padding: 0em;
+ margin: 0em;
+ font-size: 2em;
+ font-weight: bold;
+ color: #333;
+}
+
+.tip a,
+.note a {
+ color: #333;
+ text-decoration: underline;
+}
+
+.footnote {
+ font-size: small;
+ color: #333;
+}
+
+/* Changes the announcement text */
+.tip h3,
+.warning h3,
+.caution h3,
+.note h3 {
+ font-size:large;
+ color: #00557D;
+}
diff --git a/documentation/toaster-manual/toaster-manual.xml b/documentation/toaster-manual/toaster-manual.xml
new file mode 100644
index 0000000..9dac6d9
--- /dev/null
+++ b/documentation/toaster-manual/toaster-manual.xml
@@ -0,0 +1,78 @@
+<!DOCTYPE book 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; ] >
+
+<book id='toaster-manual' lang='en'
+ xmlns:xi="http://www.w3.org/2003/XInclude"
+ xmlns="http://docbook.org/ns/docbook"
+ >
+ <bookinfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref='figures/toaster-title.png'
+ format='SVG'
+ align='left' scalefit='1' width='100%'/>
+ </imageobject>
+ </mediaobject>
+
+ <title>
+ Toaster User Manual
+ </title>
+
+ <authorgroup>
+ <author>
+ <firstname>Scott</firstname> <surname>Rifenbark</surname>
+ <affiliation>
+ <orgname>Intel Corporation</orgname>
+ </affiliation>
+ <email>scott.m.rifenbark@intel.com</email>
+ </author>
+ </authorgroup>
+
+ <revhistory>
+ <revision>
+ <revnumber>1.8</revnumber>
+ <date>April 2015</date>
+ <revremark>Released with the Yocto Project 1.8 Release.</revremark>
+ </revision>
+ <revision>
+ <revnumber>1.9</revnumber>
+ <date>October 2015</date>
+ <revremark>Released with the Yocto Project 1.9 Release.</revremark>
+ </revision>
+ </revhistory>
+
+ <copyright>
+ <year>©RIGHT_YEAR;</year>
+ <holder>Linux Foundation</holder>
+ </copyright>
+
+ <legalnotice>
+ <para>
+ Permission is granted to copy, distribute and/or modify this document under
+ the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons.
+ </para>
+ <note>
+ For the latest version of this manual associated with this
+ Yocto Project release, see the
+ <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>
+ from the Yocto Project website.
+ </note>
+
+ </legalnotice>
+
+ </bookinfo>
+
+ <xi:include href="toaster-manual-intro.xml"/>
+
+ <xi:include href="toaster-manual-start.xml"/>
+
+ <xi:include href="toaster-manual-setup-and-use.xml"/>
+
+ <xi:include href="toaster-manual-reference.xml"/>
+
+</book>
+<!--
+vim: expandtab tw=80 ts=4
+-->
