toaster-manual: Added two chapter files.
Fixes [YOCTO #6901] These are the second and third chapters of the Toaster Manual. (From yocto-docs rev: 6ff4e3dfff391efdbb0f36dc6800bf115abcfc92) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
Richard Purdie
parent
e2f004faa3
commit
9d033d83cc
|
|
@ -0,0 +1,326 @@
|
|||
<!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>
|
||||
|
||||
<para>
|
||||
You can set up local and production instances of Toaster.
|
||||
This chapter describes how to set up both these types of instances.
|
||||
</para>
|
||||
|
||||
<section id='toaster-setting-up-a-local-instance'>
|
||||
<title>Setting Up a Local Instance</title>
|
||||
|
||||
<para>
|
||||
Follow these steps to set up and run a local instance of Toaster:
|
||||
<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'>What You Need and How You Get It</ulink>"
|
||||
section in the Yocto Project Quick Start for information.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Be sure Ports are free:</emphasis>
|
||||
Make sure that port 8000 and 8200 are free.
|
||||
In other words, make sure the ports do not have servers
|
||||
on them.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis>
|
||||
From your
|
||||
<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
|
||||
(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 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>
|
||||
</orderedlist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For information on how to use Toaster, see the
|
||||
"<link linkend='using-the-toaster-interface'>Using the Toaster Interface</link>"
|
||||
section.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='toaster-setting-up-a-production-instance'>
|
||||
<title>Setting Up a Production Instance</title>
|
||||
|
||||
<para>
|
||||
A production instance of Toaster resides on a server and allows
|
||||
multiple users to take advantage of Toaster.
|
||||
In a production environment, you might want to have multiple
|
||||
instances of Toaster running on various remote build machines.
|
||||
You can create this situation by basically modifying how Toaster
|
||||
starts.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Starting Toaster with the <filename>toaster</filename> command
|
||||
(i.e. the script), causes three things to start:
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
The BitBake server.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
the Toaster User Interface, which connects to the
|
||||
BitBake server on one side and to the SQL
|
||||
database on the other side.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
The web server, which reads the database and displays the
|
||||
web user interface.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
Rather than starting Toaster with the script, you can set up
|
||||
and start multiple instances of Toaster by manually starting
|
||||
as many or few of these three components across your environment.
|
||||
This is possible because it is not required that Toaster starts
|
||||
all three of its separate components in order to run.
|
||||
Minimally, an instance of Toaster requires just one of the
|
||||
components.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The concepts for setting up multiple instances of Toaster revolve
|
||||
around maintaining a common SQL database and Web server that
|
||||
show data from that common database as well as setting up
|
||||
separate instances of BitBake servers and Toaster user interfaces
|
||||
for each separate BitBake build directory.
|
||||
The common SQL database and the Web server 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 layer between the various builds.
|
||||
The database is persistent because the logging database is set
|
||||
up external to the database server (e.g. MySQL).
|
||||
It is not even necessary to run the BitBake servers, the SQL
|
||||
server, and the Web server on the same machine.
|
||||
Each component can be run on its own machine.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Follow these steps to set up and run a production instance of
|
||||
Toaster:
|
||||
<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'>What You Need and How You Get It</ulink>"
|
||||
section in the Yocto Project Quick Start for information.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Be sure Ports are free:</emphasis>
|
||||
Make sure that port 8000 and 8200 are free.
|
||||
In other words, make sure the ports do not have servers
|
||||
on them.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Set up the SQL Logging Server and the Web Server:</emphasis>
|
||||
You can use any SQL server out of the box (e.g.
|
||||
<filename>mysgl-server</filename> for an Ubuntu build
|
||||
system).
|
||||
<note>
|
||||
If you are concerned about performance, you might want
|
||||
to hand-tune the server.
|
||||
</note>
|
||||
You must set up proper username and password access for
|
||||
the server for everyone that will be using Toaster.
|
||||
You need administration rights for the
|
||||
<filename>mysql</filename> root account, which is not the
|
||||
same thing as root access on the machine.</para>
|
||||
|
||||
<para>Clone a separate, local Git repository of the
|
||||
Toaster master branch to use for running the Web server:
|
||||
<literallayout class='monospaced'>
|
||||
$ git clone (NEED THE GIT REPO URL HERE)
|
||||
</literallayout>
|
||||
You do not perform builds on this tree.
|
||||
You need to create this local repository away from any
|
||||
build areas.</para>
|
||||
|
||||
<para>In the separately cloned tree for the Web 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.</para>
|
||||
|
||||
<para>Run the database sync scripts to create the needed
|
||||
tables as follows:
|
||||
<literallayout class='monospaced'>
|
||||
$ python bitbake/lib/toaster/manage.py syncdb
|
||||
$ python bitbake/lib/toaster/manage.py migrate orm
|
||||
</literallayout>
|
||||
You can start the web server in the foreground or the
|
||||
background using these commands, respectively:
|
||||
<literallayout class='monospaced'>
|
||||
$ python bitbake/lib/toaster/manage.py runserver
|
||||
$ nohup python bitbake/lib/toaster/manage.py runserver 2>toaster_web.log >toaster_web.log &
|
||||
</literallayout>
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Enable Build Logging to the Common SQL Server for Each Build Directory you are Using</emphasis>
|
||||
For each build system that will be using Toaster and the
|
||||
SQL server, you need to edit the
|
||||
<filename>bitbake/lib/toaster/toastermain/settings.py</filename>
|
||||
to alter the <filename>DATABASES</filename> value to point
|
||||
to the common SQL logging server.
|
||||
(I DON'T SEE HOW TO DO THIS FROM THE WIKI - I NEED MORE
|
||||
CLARIFICATION).</para>
|
||||
|
||||
<para>In the Build Directory, create the required
|
||||
<filename>conf/toaster.conf</filename> file as described in
|
||||
<ulink url='https://wiki.yoctoproject.org/wiki/Setting_up_a_local_instance_of_Toaster'>BitBake Extra Options</ulink>.
|
||||
Briefly, for each Build Directory, you need to inherit the
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-toaster'>toaster</ulink>
|
||||
class by setting the following in your
|
||||
<filename>local.conf</filename> configuration file:
|
||||
<literallayout class='monospaced'>
|
||||
INHERIT += "toaster"
|
||||
INHERIT += "buildhistory"
|
||||
BUILDHISTORY_COMMIT = "1"
|
||||
</literallayout>
|
||||
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>
|
||||
Start the logging user 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 as there is enough code
|
||||
to run <filename>autodiscovery</filename>
|
||||
for ports to prevent collisions.
|
||||
</note>
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis>
|
||||
From your
|
||||
<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build 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 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 Toaster, see the
|
||||
"<link linkend='using-the-toaster-interface'>Using the Toaster Interface</link>"
|
||||
section.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='setting-up-a-hosted-managed-mode-for-toaster'>
|
||||
<title>Setting Up a Hosted Managed Mode for Toaster</title>
|
||||
|
||||
<para>
|
||||
(RIGHT NOW, THE
|
||||
<ulink url='https://wiki.yoctoproject.org/wiki/Setting_up_a_hosted_managed_mode_for_Toaster'>WIKI PAGE</ulink>
|
||||
HAS SOME INFORMATION ON THIS.
|
||||
I DON'T GET IT THOUGH.
|
||||
I NEED SOME MORE INFORMATION IN ORDER TO UNDERSTAND THIS AND
|
||||
CREATE A SECTION.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='using-the-toaster-interface'>
|
||||
<title>Using the Toaster Interface</title>
|
||||
|
||||
<para>
|
||||
The Toaster interface allows you to examine the following:
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
Outcome of the build, errors and warnings thrown
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
Packages included in an image
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
Image directory structure
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
Build configuration
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
Recipes and packages built
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
Full dependency chain for tasks, recipes and packages
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
Tasks run by the build system
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
Performance information such as time, CPU usage, and
|
||||
disk I/O per task
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
For several useful videos that show how to effectively use the
|
||||
Toaster interface, see the
|
||||
<ulink url='https://www.yoctoproject.org/documentation/toaster-manual-17'>Toaster Documentation</ulink>
|
||||
on the Yocto Project website.
|
||||
(SO WE NEED TO DECIDE IF THESE VIDS ARE GOING TO ROLL OVER INTO
|
||||
1.8 AND REMAIN ON A "TOASTER MANUAL" PAGE AS THEY DO IN 1.7.
|
||||
OR, IF WE ARE GOING TO GET THE LINKS TO THE VIDS HERE IN THIS
|
||||
MANUAL.)
|
||||
</para>
|
||||
</section>
|
||||
</chapter>
|
||||
|
||||
|
||||
<!--
|
||||
vim: expandtab tw=80 ts=4
|
||||
-->
|
||||
|
|
@ -0,0 +1,75 @@
|
|||
<!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.
|
||||
Toaster requires some packages that you must have installed before trying
|
||||
to run 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'>What You Need and How You Get It</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 that Bitbake
|
||||
does not need in order to run.
|
||||
In order to make it easy to run Toaster, a requirements file
|
||||
located in the root directory of
|
||||
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
|
||||
<filename>bitbake/</filename>
|
||||
(e.g. <filename>poky/bitbake/toaster-requirements.txt</filename>).
|
||||
The dependencies appear in a <filename>pip</filename>,
|
||||
install-compatible format:
|
||||
<literallayout class='monospaced'>
|
||||
Django==1.6
|
||||
South==0.8.4
|
||||
argparse==1.2.1
|
||||
wsgiref==0.1.2
|
||||
</literallayout>
|
||||
Follow these steps to get set up:
|
||||
<orderedlist>
|
||||
<listitem><para><emphasis>Create and activate a virtual environment:</emphasis>
|
||||
<literallayout class='monospaced'>
|
||||
$ virtualenv venv
|
||||
$ source venv/bin/activate
|
||||
</literallayout>
|
||||
</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>
|
||||
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>
|
||||
</section>
|
||||
|
||||
</chapter>
|
||||
<!--
|
||||
vim: expandtab tw=80 ts=4
|
||||
-->
|
||||
Loading…
Reference in New Issue