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>

2 files changed, 401 insertions, 0 deletions

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 0000000000..ac9e9313ff
--- /dev/null
+++ b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
@@ -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 &amp;
+                    </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 &amp;&amp; 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 &amp;
+                    </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
+-->
diff --git a/documentation/toaster-manual/toaster-manual-start.xml b/documentation/toaster-manual/toaster-manual-start.xml
new file mode 100644
index 0000000000..93f48c7b26
--- /dev/null
+++ b/documentation/toaster-manual/toaster-manual-start.xml
@@ -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
+-->