diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2015-02-03 11:09:28 -0800 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2015-02-17 15:16:58 +0000 |
commit | 9d033d83cc8d31c9cf545231119f85a2cf9d0154 (patch) | |
tree | 96c5e6eefbd441ad1caf7b77bb7aa8eae1429f87 /documentation/toaster-manual | |
parent | e2f004faa3bf4bca0f12e86bc8b57d964a8ca818 (diff) | |
download | openembedded-core-contrib-9d033d83cc8d31c9cf545231119f85a2cf9d0154.tar.gz |
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>
Diffstat (limited to 'documentation/toaster-manual')
-rw-r--r-- | documentation/toaster-manual/toaster-manual-setup-and-use.xml | 326 | ||||
-rw-r--r-- | documentation/toaster-manual/toaster-manual-start.xml | 75 |
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 & + </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 +--> 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 +--> |