toaster-manual: Draft of Manual.
Fixes [YOCTO #6901] (From yocto-docs rev: 258b46b0f3e23045b5fb8c97d03dceb69db5ce20) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
parent
9e4adec98d
commit
85a0b9b941
|
@ -0,0 +1,22 @@
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<xsl:stylesheet version="1.0"
|
||||||
|
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
|
||||||
|
xmlns:d="http://docbook.org/ns/docbook">
|
||||||
|
|
||||||
|
<xsl:output method="html" />
|
||||||
|
|
||||||
|
<xsl:template match="/d:chapter/d:section/d:mediaobject">
|
||||||
|
<xsl:for-each select=".">
|
||||||
|
<xsl:variable name="vid_url">
|
||||||
|
<xsl:value-of select="./d:videoobject/d:videodata/@fileref" />
|
||||||
|
</xsl:variable>
|
||||||
|
<div style="text-align: center; margin: auto">
|
||||||
|
<object type="application/x-shockwave-flash" width="640" height="420" data="{$vid_url}?color2=FBE9EC&showsearch=0&version=3&modestbranding=1&fs=1">
|
||||||
|
<param name="movie" value="{$vid_url}?color2=FBE9EC&showsearch=0&version=3&modestbranding=1&fs=1" />
|
||||||
|
<param name="allowFullScreen" value="true" />
|
||||||
|
<param name="allowscriptaccess" value="always" />
|
||||||
|
</object>
|
||||||
|
</div>
|
||||||
|
</xsl:for-each>
|
||||||
|
</xsl:template>
|
||||||
|
</xsl:stylesheet>
|
Binary file not shown.
After Width: | Height: | Size: 13 KiB |
Binary file not shown.
After Width: | Height: | Size: 10 KiB |
|
@ -1,13 +1,15 @@
|
||||||
<?xml version='1.0'?>
|
<?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: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://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" />
|
<!-- <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" /> -->
|
||||||
|
<xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
|
||||||
|
|
||||||
<xsl:include href="../template/permalinks.xsl"/>
|
<xsl:include href="../template/permalinks.xsl"/>
|
||||||
<xsl:include href="../template/section.title.xsl"/>
|
<xsl:include href="../template/section.title.xsl"/>
|
||||||
<xsl:include href="../template/component.title.xsl"/>
|
<xsl:include href="../template/component.title.xsl"/>
|
||||||
<xsl:include href="../template/division.title.xsl"/>
|
<xsl:include href="../template/division.title.xsl"/>
|
||||||
<xsl:include href="../template/formal.object.heading.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="html.stylesheet" select="'toaster-manual-style.css'" />
|
||||||
<xsl:param name="chapter.autolabel" select="1" />
|
<xsl:param name="chapter.autolabel" select="1" />
|
||||||
|
|
|
@ -6,95 +6,12 @@
|
||||||
<title>Introduction</title>
|
<title>Introduction</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Toaster is web interface to the OpenEmbedded build system, which uses
|
Toaster is a web interface to the Yocto Project's
|
||||||
BitBake.
|
<ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.
|
||||||
The interface allows you to access a datastore that retains build
|
The interface enables you to configure and run your builds.
|
||||||
information and report out on the information.
|
Information about builds is collected and stored in a database.
|
||||||
</para>
|
You can use Toaster to configure and start builds on multiple
|
||||||
<!--THE FOLLOWING IS DETAIL THAT I THINK BELEN WANTED OUT FOR THE MOMENT
|
remote build servers.
|
||||||
The interface is based on a Representational State Transfer
|
|
||||||
(REST) API that queries for and returns build information using
|
|
||||||
<filename>GET</filename> and <filename>JSON</filename>.
|
|
||||||
These types of search operations retrieve sets of objects from
|
|
||||||
a datastore used to collect build information.
|
|
||||||
The results contain all the data for the objects being returned.
|
|
||||||
You can order the results of the search by key and the search
|
|
||||||
parameters are consistent for all object types.
|
|
||||||
</para>
|
|
||||||
-->
|
|
||||||
|
|
||||||
<para>
|
|
||||||
You can use Toaster in several different modes:
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem><para><emphasis>Analysis Mode:</emphasis>
|
|
||||||
In this mode, you can record builds and statistics.
|
|
||||||
In Analysis Mode, you have direct access to the
|
|
||||||
<filename>bitbake</filename> command, which you 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></listitem>
|
|
||||||
<listitem><para><emphasis>Build Mode:</emphasis>
|
|
||||||
In this mode, Toaster handles the build configuration GUI
|
|
||||||
(through project pages) and build 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
|
|
||||||
with Toaster's GUI.
|
|
||||||
Each configuration is a project, which requires version and
|
|
||||||
build system selection.
|
|
||||||
As shipped, Toaster supports the Yocto Project releases
|
|
||||||
1.8 and beyond.
|
|
||||||
Aside from these supported releases, you can also select
|
|
||||||
the "Local Yocto Project", which allows you to use your
|
|
||||||
local clone of the Yocto Project
|
|
||||||
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
|
|
||||||
(e.g. <filename>poky</filename>).</para>
|
|
||||||
<para>Build Mode also works two separate ways: locally and
|
|
||||||
remotely.
|
|
||||||
While you can use Build Mode locally, it is best to use
|
|
||||||
Toaster's Build Mode through a hosted service where it can
|
|
||||||
shared by multiple user.
|
|
||||||
</para></listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Using Toaster, you can do the following:
|
|
||||||
<note><title>REVIEWER NOTE</title>
|
|
||||||
Belen suggested we split this list out into things that
|
|
||||||
Analysis Mode and Build Mode can do.
|
|
||||||
Also, we can structure the lists so the Build Mode list
|
|
||||||
leverages off what is listed for Analysis Mode.
|
|
||||||
I do not know the information for the complete lists.
|
|
||||||
Someone needs to help me out here.
|
|
||||||
For now, I am leaving the list as follows and will need some
|
|
||||||
information.
|
|
||||||
</note>
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem><para>
|
|
||||||
See information about the tasks executed
|
|
||||||
and reused during the build.
|
|
||||||
</para></listitem>
|
|
||||||
<listitem><para>
|
|
||||||
See what is built (recipes and
|
|
||||||
packages) and what packages were installed into the final
|
|
||||||
image.
|
|
||||||
</para></listitem>
|
|
||||||
<listitem><para>
|
|
||||||
See performance-related information such
|
|
||||||
as build time, CPU usage, and disk I/O.
|
|
||||||
</para></listitem>
|
|
||||||
<listitem><para>
|
|
||||||
Examine error, warning and trace messages
|
|
||||||
to aid in debugging.
|
|
||||||
</para></listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<note>
|
<note>
|
||||||
|
@ -116,10 +33,131 @@
|
||||||
</para>
|
</para>
|
||||||
</note>
|
</note>
|
||||||
|
|
||||||
|
<section id='intro-modes'>
|
||||||
|
<title>Toaster Operational Modes</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The remainder of this manual describes what you need to have in
|
You can use Toaster in Analysis Mode or Build Mode:
|
||||||
place to use Toaster, how to start it, use it, and stop it.
|
<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>
|
</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
|
<!--THIS EXTRA INFORMATION PROBABLY WILL GO AWAY
|
||||||
For additional information on installing and running Toaster, see the
|
For additional information on installing and running Toaster, see the
|
||||||
|
|
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
|
@ -9,8 +9,6 @@
|
||||||
<para>
|
<para>
|
||||||
This chapter describes how you need to prepare your system in order to
|
This chapter describes how you need to prepare your system in order to
|
||||||
use Toaster.
|
use Toaster.
|
||||||
Toaster requires some packages that you must have installed before
|
|
||||||
trying to run Toaster.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<section id='toaster-setting-up-the-basic-system-requirements'>
|
<section id='toaster-setting-up-the-basic-system-requirements'>
|
||||||
|
@ -30,54 +28,103 @@
|
||||||
<title>Establishing Toaster System Dependencies</title>
|
<title>Establishing Toaster System Dependencies</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Toaster requires extra Python dependencies that Bitbake
|
Toaster requires extra Python dependencies and
|
||||||
does not need in order to run.
|
<ulink url='http://www.libslack.org/daemon/'><filename>daemon</filename></ulink>
|
||||||
In order to make it easy to run Toaster, a requirements file
|
in order to run.
|
||||||
located in the root directory of
|
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>
|
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
|
||||||
<filename>bitbake/</filename>
|
|
||||||
(e.g. <filename>poky/bitbake/toaster-requirements.txt</filename>).
|
(e.g. <filename>poky/bitbake/toaster-requirements.txt</filename>).
|
||||||
The dependencies appear in a <filename>pip</filename>,
|
The dependencies appear in a <filename>pip</filename>,
|
||||||
install-compatible format:
|
install-compatible format.
|
||||||
<literallayout class='monospaced'>
|
</para>
|
||||||
Django==1.6
|
|
||||||
South==0.8.4
|
<section id='toaster-optional-virtual-environment'>
|
||||||
argparse==1.2.1
|
<title>Optionally Setting Up a Python Virtual Environment</title>
|
||||||
wsgiref==0.1.2
|
|
||||||
</literallayout>
|
<para>
|
||||||
Follow these steps to get set up:
|
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>
|
<orderedlist>
|
||||||
<listitem><para><emphasis>Install <filename>virtualenv</filename>:</emphasis>
|
<listitem><para><emphasis>Install <filename>virtualenv</filename>:</emphasis>
|
||||||
<filename>virtualenv</filename> is a tool to create
|
Install the supported
|
||||||
isolated Python environments by creating folders that
|
<filename>python-virtualenv</filename> package from your
|
||||||
contain all the necessary executables to use the packages
|
distribution rather than using <filename>pip</filename>.
|
||||||
that Python projects need.
|
|
||||||
You can use <filename>pip</filename> to install
|
|
||||||
<filename>virtualenv</filename>:
|
|
||||||
<literallayout class='monospaced'>
|
<literallayout class='monospaced'>
|
||||||
$ pip install virtualenv
|
$ sudo apt-get install python-virtualenv
|
||||||
</literallayout>
|
</literallayout>
|
||||||
</para></listitem>
|
</para></listitem>
|
||||||
<listitem><para><emphasis>Create and activate a virtual environment:</emphasis>
|
<listitem><para><emphasis>Create and Activate a Virtual Environment:</emphasis>
|
||||||
<literallayout class='monospaced'>
|
<literallayout class='monospaced'>
|
||||||
$ virtualenv venv
|
$ virtualenv venv
|
||||||
$ source venv/bin/activate
|
$ source venv/bin/activate
|
||||||
</literallayout>
|
</literallayout>
|
||||||
</para></listitem>
|
</para></listitem>
|
||||||
<listitem><para><emphasis>Use <filename>pip</filename> to install needed packages:</emphasis>
|
|
||||||
<literallayout class='monospaced'>
|
|
||||||
$ pip install -r bitbake/toaster-requirements.txt
|
|
||||||
</literallayout>
|
|
||||||
</para></listitem>
|
|
||||||
</orderedlist>
|
</orderedlist>
|
||||||
Once you complete these steps, you execute in a lightweight
|
|
||||||
"virtual environment” with its own site directories that are
|
|
||||||
optionally isolated from system site directories.
|
|
||||||
The virtual environment has its own Python binary
|
|
||||||
(allowing creation of environments with various Python versions)
|
|
||||||
and can have its own independent set of installed Python packages
|
|
||||||
in its site directories.
|
|
||||||
</para>
|
</para>
|
||||||
</section>
|
</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>
|
||||||
|
|
||||||
|
<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>
|
</chapter>
|
||||||
|
|
|
@ -65,6 +65,8 @@
|
||||||
|
|
||||||
<xi:include href="toaster-manual-setup-and-use.xml"/>
|
<xi:include href="toaster-manual-setup-and-use.xml"/>
|
||||||
|
|
||||||
|
<xi:include href="toaster-manual-reference.xml"/>
|
||||||
|
|
||||||
</book>
|
</book>
|
||||||
<!--
|
<!--
|
||||||
vim: expandtab tw=80 ts=4
|
vim: expandtab tw=80 ts=4
|
||||||
|
|
Loading…
Reference in New Issue