diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2015-02-18 06:24:18 -0800 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2015-04-01 12:59:10 +0100 |
commit | 85a0b9b941fbd38d44e4802a27290ad9ec4bb963 (patch) | |
tree | 92bf61d40674f0b28fd44af49daa38b215de3b73 | |
parent | 9e4adec98db325112ca7a8b9dd95722d4d0ab642 (diff) | |
download | openembedded-core-contrib-85a0b9b941fbd38d44e4802a27290ad9ec4bb963.tar.gz |
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>
-rw-r--r-- | documentation/template/embedded_video.xsl | 22 | ||||
-rw-r--r-- | documentation/toaster-manual/figures/hosted-service.png | bin | 0 -> 13552 bytes | |||
-rw-r--r-- | documentation/toaster-manual/figures/simple-configuration.png | bin | 0 -> 10789 bytes | |||
-rw-r--r-- | documentation/toaster-manual/toaster-manual-customization.xsl | 4 | ||||
-rw-r--r-- | documentation/toaster-manual/toaster-manual-intro.xml | 224 | ||||
-rw-r--r-- | documentation/toaster-manual/toaster-manual-reference.xml | 1069 | ||||
-rw-r--r-- | documentation/toaster-manual/toaster-manual-setup-and-use.xml | 920 | ||||
-rw-r--r-- | documentation/toaster-manual/toaster-manual-start.xml | 137 | ||||
-rw-r--r-- | documentation/toaster-manual/toaster-manual.xml | 2 |
9 files changed, 2084 insertions, 294 deletions
diff --git a/documentation/template/embedded_video.xsl b/documentation/template/embedded_video.xsl new file mode 100644 index 0000000000..dfb33c3441 --- /dev/null +++ b/documentation/template/embedded_video.xsl @@ -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> diff --git a/documentation/toaster-manual/figures/hosted-service.png b/documentation/toaster-manual/figures/hosted-service.png Binary files differnew file mode 100644 index 0000000000..01fea7b245 --- /dev/null +++ b/documentation/toaster-manual/figures/hosted-service.png diff --git a/documentation/toaster-manual/figures/simple-configuration.png b/documentation/toaster-manual/figures/simple-configuration.png Binary files differnew file mode 100644 index 0000000000..e8fce2bf18 --- /dev/null +++ b/documentation/toaster-manual/figures/simple-configuration.png diff --git a/documentation/toaster-manual/toaster-manual-customization.xsl b/documentation/toaster-manual/toaster-manual-customization.xsl index e253aedd9a..29d29c452e 100644 --- a/documentation/toaster-manual/toaster-manual-customization.xsl +++ b/documentation/toaster-manual/toaster-manual-customization.xsl @@ -1,13 +1,15 @@ <?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://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/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" /> diff --git a/documentation/toaster-manual/toaster-manual-intro.xml b/documentation/toaster-manual/toaster-manual-intro.xml index 378f33420c..ad9e08b50d 100644 --- a/documentation/toaster-manual/toaster-manual-intro.xml +++ b/documentation/toaster-manual/toaster-manual-intro.xml @@ -6,95 +6,12 @@ <title>Introduction</title> <para> - Toaster is web interface to the OpenEmbedded build system, which uses - BitBake. - The interface allows you to access a datastore that retains build - information and report out on the information. - </para> -<!--THE FOLLOWING IS DETAIL THAT I THINK BELEN WANTED OUT FOR THE MOMENT - 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> + 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> @@ -116,10 +33,131 @@ </para> </note> - <para> - The remainder of this manual describes what you need to have in - place to use Toaster, how to start it, use it, and stop it. - </para> + <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 diff --git a/documentation/toaster-manual/toaster-manual-reference.xml b/documentation/toaster-manual/toaster-manual-reference.xml new file mode 100644 index 0000000000..05184fa1eb --- /dev/null +++ b/documentation/toaster-manual/toaster-manual-reference.xml @@ -0,0 +1,1069 @@ +<!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. + 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 reference. + However, having relevant command useful for the Toaster context + is helpful. + </para> + + <section id='layer-source'> + <title>Layer Source</title> + + <para> + In general, a layer source is some source of 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. + </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>Select 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 + information from the layer index to populate the + Toaster database with the information from your layer + index. + 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 index should be listed there. + </para> + </section> + </section> + </section> + </section> + + <section id='toaster-releases'> + <title>Releases</title> + + <para> + 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. + When you create a Toaster project using the web interface, + you are asked to choose a "Release." + 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. + You can download the recommended configuration + for this case from + <ulink url='&YOCTO_WIKI_URL;/wiki/File:Toasterconf.json.txt.patch'></ulink>. + </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 sets it to + use the master branch of the + <filename>openembedded-core</filename> layer. + 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 the 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 + admin web 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. + In the Local Toaster 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, 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 three + versions of BitBake: master, dizzy, and HEAD. + </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. + For example, assuming default repository and build directory + names, the following two commands put you in the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + and then return a list of the current builds, which would + be one in this case: + <literallayout class='monospaced'> + $ cd $HOME/poky/build + $ python ../bitbake/lib/toaster/manage.py buildslist + 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 Managed 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 a 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 <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 launched + 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 "toasterui" build recorded 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 index f56d67ed37..b148d4f405 100644 --- a/documentation/toaster-manual/toaster-manual-setup-and-use.xml +++ b/documentation/toaster-manual/toaster-manual-setup-and-use.xml @@ -6,12 +6,6 @@ <title>Setting Up and Using Toaster</title> - <para> - You can set up Toaster as a local instance or as a hosted service. - Furthermore, you can use Toaster in Analysis Mode or Build Mode - from both set ups. - </para> - <section id='using-toaster-in-analysis-mode'> <title>Using Toaster in Analysis Mode</title> @@ -41,19 +35,14 @@ "<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> + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> (e.g. <filename>poky/build</filename>), source the build - environment setup script (i.e. + 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>). + <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 @@ -72,13 +61,20 @@ $ 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> - For information on how to use Toaster, see the - "<link linkend='using-the-toaster-interface'>Using the Toaster Interface</link>" - section. + </para> </section> @@ -86,68 +82,45 @@ <title>Setting Up a Hosted Service and Running in Analysis Mode</title> <para> - A hosted service resides on a server and allows + A hosted service resides on a shared server and allows multiple users to take advantage of Toaster. - In a production environment, you might want to have multiple - local instances of Toaster, which run on various remote - build machines, and have those local instances access and use - a single hosted Toaster service. </para> <para> - Starting Toaster with the <filename>toaster</filename> command - (i.e. the script), causes three things to start: + 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> - 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. + Maintain a common SQL database. </para></listitem> <listitem><para> - The web server, which reads the database and displays - the web user interface. + Set up separate instances of BitBake servers + and Toaster Logging Interfaces for each of those + separate BitBake servers. </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, a local instance of Toaster requires just one of the - components. </para> <para> - The concepts for setting up multiple local instances of - Toaster that share a single hosted service revolve - around maintaining a common SQL database and Web server that - shows data from that common database as well as setting up - separate local instances of BitBake servers and Toaster user - interfaces for each of those separate BitBake build - directories. - </para> - - <para> - The common SQL database and the Web server show data from + 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 layer between the various local builds - and the common database. - The database is persistent because the logging database is set - up external to the BitBake 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. + 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 @@ -162,71 +135,153 @@ "<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 on - the shared 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. - The Git repository for Toaster is part of the - Yocto Project - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. - Consequently, you just need to set up a separate - local clone of the Yocto Project Source Directory - (e.g. <filename>poky</filename>): + <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> - 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, + 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.</para> - <para>Run the database sync scripts to create the - needed tables as follows: + 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 + <filename>django</filename> WSGI. + 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'> - $ python bitbake/lib/toaster/manage.py syncdb - $ python bitbake/lib/toaster/manage.py migrate orm + $ 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> - You can start the Web server in the foreground or the - background using these commands, respectively: + </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'> - $ python bitbake/lib/toaster/manage.py runserver - $ nohup python bitbake/lib/toaster/manage.py runserver 2>toaster_web.log >toaster_web.log & + $ /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> - For each build system that will be using Toaster and - the shared SQL server, you need to edit the - <filename>bitbake/lib/toaster/toastermain/settings.py</filename> - file to alter the <filename>DATABASES</filename> value - so that it points to the common SQL logging server. - <note><title>REVIEWER NOTE</title> - I don't see how to do this from the Wiki. - I need more clarification. - </note></para> - <para>In the Build Directory, create the required + 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>. @@ -240,24 +295,16 @@ INHERIT += "buildhistory" BUILDHISTORY_COMMIT = "1" </literallayout> - Start the BitBake server using the following command: + You also need to point to the database. + You can do this by exporting the + <filename>DATABASE_URL</filename> variable as follows: <literallayout class='monospaced'> - $ bitbake ‐‐postread conf/toaster.conf ‐‐server-only -t xmlrpc -B localhost:0 && export BBSERVER=localhost:-1 + export DATABASE_URL=mysql://<replaceable>newuser</replaceable>:<replaceable>password</replaceable>@192.168.0.25:3306/toaster </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> + <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. @@ -265,6 +312,26 @@ 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. @@ -284,8 +351,9 @@ </para> <para> - For information on how to use Toaster, see the - "<link linkend='using-the-toaster-interface'>Using the Toaster Interface</link>" + 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> @@ -303,65 +371,607 @@ <section id='setting-up-locally-and-running-in-build-mode'> <title>Setting Up Locally and Running in Build Mode</title> - <note><title>REVIEWER NOTE</title> - I need the information on how to do this. - </note> + <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'>What You Need and How You Get It</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> and supports + several types. + 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> - <note><title>REVIEWER NOTE</title> - 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 but I don't understand it. - I need more information. - </note> + <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'>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 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>Configure the Build Environment:</emphasis> + Configure the build environment by running the + following: + <literallayout class='monospaced'> + bitbake/lib/toaster/manage.py checksettings + </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>Load a Configuration File:</emphasis> + Load a configuration file by running the following: + <literallayout class='monospaced'> + bitbake/lib/toaster/manage.py loadconf <replaceable>path-to-toasterconf.json-file</replaceable> + </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>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 infor 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 "poky" user. + 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> + Download the <filename>toasterconf.json</filename> file + from the + <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>File:Toasterconf.json.txt.patch</ulink> + wiki page 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></listitem> + <listitem><para><emphasis>Check the Toaster Settings:</emphasis> + You can check the Toaster settings by running this + command: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py checksettings + </literallayout> + When prompted, paste in the directory paths created + previously during Step 9. + Alternatively, you can select the edited + <filename>toasterconf.json</filename> file set up in + Step 5. + </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 + <filename>django</filename> WSGI. + 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. + You can track accesses and errors in the Apache + service logs: + <literallayout class='monospaced'> + http://localhost:8000/toastergui + </literallayout> + You can now use the Toaster web interface. + </para></listitem> + </orderedlist> + </para> </section> </section> - <section id='using-the-toaster-interface'> - <title>Using the Toaster Interface</title> + <section id='using-the-toaster-web-interface'> + <title>Using the Toaster Web Interface</title> <para> - The Toaster interface allows you to examine the following: + The Toaster web interface allows you to do the following: <itemizedlist> <listitem><para> - Outcome of the build, errors and warnings thrown + Browse all OpenEmbedded layers available for your + selected version of the build system + </para></listitem> + <listitem><para> + Import your own layers for building. </para></listitem> <listitem><para> - Packages included in an image + Add and remove layers from your configuration. </para></listitem> <listitem><para> - Image directory structure + Set configuration variables. </para></listitem> <listitem><para> - Build configuration + Select a target or multiple targets to build. </para></listitem> <listitem><para> - Recipes and packages built + Start your builds. </para></listitem> <listitem><para> - Full dependency chain for tasks, recipes and packages + See what was built (recipes and packages) and what + packages were installed into your final image. </para></listitem> <listitem><para> - Tasks run by the build system + Browse the directory structure of your image. </para></listitem> <listitem><para> - Performance information such as time, CPU usage, and - disk I/O per task + 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> - 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. - <note><title>REVIEWER NOTE</title> - We have agreed to get rid of the manual page on the website, - contains the links to the GUI videos. - We have agreed to host the videos on Vimeo and to embed the - videos in this new Toaster manual. - </note> + Following are several videos that show how to use the Toaster GUI. + To get a larger replay of a video after it has started playing, + click in the image title area. </para> + + <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> + </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> </section> </chapter> diff --git a/documentation/toaster-manual/toaster-manual-start.xml b/documentation/toaster-manual/toaster-manual-start.xml index b884036035..608a505fac 100644 --- a/documentation/toaster-manual/toaster-manual-start.xml +++ b/documentation/toaster-manual/toaster-manual-start.xml @@ -9,8 +9,6 @@ <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'> @@ -30,54 +28,103 @@ <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 + Toaster requires extra Python dependencies and + <ulink url='http://www.libslack.org/daemon/'><filename>daemon</filename></ulink> + 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> - <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>Install <filename>virtualenv</filename>:</emphasis> - <filename>virtualenv</filename> is a tool to create - isolated Python environments by creating folders that - contain all the necessary executables to use the packages - that Python projects need. - You can use <filename>pip</filename> to install - <filename>virtualenv</filename>: - <literallayout class='monospaced'> - $ pip install virtualenv - </literallayout> - </para></listitem> - <listitem><para><emphasis>Create and activate a virtual environment:</emphasis> - <literallayout class='monospaced'> + 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> - <listitem><para><emphasis>Use <filename>pip</filename> to install needed packages:</emphasis> - <literallayout class='monospaced'> + </literallayout> + </para></listitem> + </orderedlist> + </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></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> + </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> diff --git a/documentation/toaster-manual/toaster-manual.xml b/documentation/toaster-manual/toaster-manual.xml index cc27aaa67e..7371ca2b8d 100644 --- a/documentation/toaster-manual/toaster-manual.xml +++ b/documentation/toaster-manual/toaster-manual.xml @@ -65,6 +65,8 @@ <xi:include href="toaster-manual-setup-and-use.xml"/> + <xi:include href="toaster-manual-reference.xml"/> + </book> <!-- vim: expandtab tw=80 ts=4 |