diff options
Diffstat (limited to 'documentation/toaster-manual')
| -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/figures/toaster-title.png | bin | 0 -> 9277 bytes | |||
| -rw-r--r-- | documentation/toaster-manual/toaster-manual-customization.xsl | 21 | ||||
| -rw-r--r-- | documentation/toaster-manual/toaster-manual-intro.xml | 172 | ||||
| -rw-r--r-- | documentation/toaster-manual/toaster-manual-reference.xml | 1073 | ||||
| -rw-r--r-- | documentation/toaster-manual/toaster-manual-setup-and-use.xml | 1024 | ||||
| -rw-r--r-- | documentation/toaster-manual/toaster-manual-start.xml | 141 | ||||
| -rw-r--r-- | documentation/toaster-manual/toaster-manual-style.css | 984 | ||||
| -rw-r--r-- | documentation/toaster-manual/toaster-manual.xml | 73 |
10 files changed, 3488 insertions, 0 deletions
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/figures/toaster-title.png b/documentation/toaster-manual/figures/toaster-title.png Binary files differnew file mode 100644 index 0000000000..b7ea39cd8d --- /dev/null +++ b/documentation/toaster-manual/figures/toaster-title.png diff --git a/documentation/toaster-manual/toaster-manual-customization.xsl b/documentation/toaster-manual/toaster-manual-customization.xsl new file mode 100644 index 0000000000..dcf7805d4c --- /dev/null +++ b/documentation/toaster-manual/toaster-manual-customization.xsl @@ -0,0 +1,21 @@ +<?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="../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" /> + <xsl:param name="appendix.autolabel" select="A" /> + <xsl:param name="section.autolabel" select="1" /> + <xsl:param name="section.label.includes.component.label" select="1" /> + <xsl:param name="generate.id.attributes" select="1" /> + +</xsl:stylesheet> diff --git a/documentation/toaster-manual/toaster-manual-intro.xml b/documentation/toaster-manual/toaster-manual-intro.xml new file mode 100644 index 0000000000..ad9e08b50d --- /dev/null +++ b/documentation/toaster-manual/toaster-manual-intro.xml @@ -0,0 +1,172 @@ +<!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-intro'> +<title>Introduction</title> + + <para> + 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> + <para> + This release of Toaster does allow you to configure and initiate + builds. + However, you cannot use Toaster to customize image recipes, which + still must either be done by hand or through + <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>. + As Toaster matures, it eventually will equal and surpass Hob + functionality, at which time Hob will be deprecated. + </para> + + <para> + For more information on Hob, + see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#image-development-using-hob'>Image Development Using Hob</ulink>" + section in the Yocto Project Development Manual. + </para> + </note> + + <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 + "<ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Installation_and_Running'>Installation and Running</ulink>" + section of the "Toaster" wiki page. + For complete information on the API and its search operation + URI, parameters, and responses, see the + <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink> + Wiki page. + </para> +--> +</chapter> diff --git a/documentation/toaster-manual/toaster-manual-reference.xml b/documentation/toaster-manual/toaster-manual-reference.xml new file mode 100644 index 0000000000..fede4529a2 --- /dev/null +++ b/documentation/toaster-manual/toaster-manual-reference.xml @@ -0,0 +1,1073 @@ +<!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 that are Toaster-specific. + 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 comprehensive reference. + </para> + + <section id='layer-source'> + <title>Layer Source</title> + + <para> + In general, a "layer source" is a source of information about + 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>Use 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 + Toaster database with the information coming from your + new layer source. + 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 source should be listed there. + </para> + </section> + </section> + </section> + </section> + + <section id='toaster-releases'> + <title>Releases</title> + + <para> + When you create a Toaster project using the web interface, + you are asked to choose a "Release." + 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. + 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. + </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 uses the + "master" branch provided by the layer source of type + "layerindex", which is called "OpenEmbedded", and sets + the <filename>openembedded-core</filename> layer as the one + to be added by default to any projects created in Toaster. + 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 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 + Django administration 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. + When you set up Toaster locally to run in 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 release, 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 four + versions of BitBake: master, fido, dizzy, and HEAD. + <note> + HEAD is a special option that builds whatever is + available on disk, without checking out any remote + Git repositories. + </note> + </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. + Here is an example that assumes default repository and build + directory names: + <literallayout class='monospaced'> + $ cd ~/poky/build + $ python ../bitbake/lib/toaster/manage.py buildslist + </literallayout> + If your Toaster database had only one build, the above + <filename>buildslist</filename> command would return something + like the following: + <literallayout class='monospaced'> + 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 Build 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 an + existing 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 existing + <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 launches + 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 Toaster Logging Interface records and 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 new file mode 100644 index 0000000000..a1546858d9 --- /dev/null +++ b/documentation/toaster-manual/toaster-manual-setup-and-use.xml @@ -0,0 +1,1024 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<chapter id='toaster-manual-setup-and-use'> + +<title>Setting Up and Using Toaster</title> + + <section id='using-toaster-in-analysis-mode'> + <title>Using Toaster in Analysis Mode</title> + + <para> + This section describes how to use Toaster in Analysis Mode + after setting Toaster up as a local instance or as a hosted + service. + </para> + + <section id='setting-up-locally-and-running-in-analysis-mode'> + <title>Setting Up Locally and Running in Analysis Mode</title> + + <para> + Follow these steps to set up a local instance of Toaster and + then run in Analysis 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>Source your Build Environment Setup Script:</emphasis> + From your + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + (e.g. <filename>poky/build</filename>), source the build + 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>. + </para></listitem> + <listitem><para><emphasis>Start Toaster:</emphasis> + From the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, + start Toaster: + <literallayout class='monospaced'> + $ source toaster start + </literallayout> + </para></listitem> + <listitem><para><emphasis>Start Your Build Using BitBake:</emphasis> + Use the <filename>bitbake</filename> command to start your + build. + Here is an example that builds the + <filename>core-image-minimal</filename> image: + <literallayout class='monospaced'> + $ bitbake core-image-minimal + </literallayout> + </para></listitem> + <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> + + </para> + </section> + + <section id='setting-up-a-hosted-service-and-running-in-analysis-mode'> + <title>Setting Up a Hosted Service and Running in Analysis Mode</title> + + <para> + A hosted service resides on a shared server and allows + multiple users to take advantage of Toaster. + </para> + + <para> + 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> + Maintain a common SQL database. + </para></listitem> + <listitem><para> + Set up separate instances of BitBake servers + and Toaster Logging Interfaces for each of those + separate BitBake servers. + </para></listitem> + </itemizedlist> + </para> + + <para> + 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 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 + 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>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>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 + <ulink url='https://docs.djangoproject.com/en/1.7/howto/deployment/wsgi/'><filename>django</filename> WSGI</ulink>. + 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> + 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> + You need to make sure that the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-toaster'><filename>toaster</filename></ulink> + class and build history are enabled. + This is done in a + <filename>toaster.conf</filename> file that is + created automatically by the toaster + <filename>start</filename> command, + and that lives inside the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + in <filename>/conf/toaster.conf</filename>.</para> + <para>That file should include the following line: + <literallayout class='monospaced'> + INHERIT += "toaster buildhistory" + </literallayout> + For information on build history, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>" + section in the Yocto Project Development + Manual.</para> + <para>You also need to point to the database that you set + up in step 3. + You can do this by exporting the <filename>DATABASE_URL</filename> + variable as follows: + <literallayout class='monospaced'> + export DATABASE_URL=mysql://newuser:password@192.168.0.25:3306/toaster + </literallayout> + This example assumes that you are using + <filename>mysql-server</filename>. + The IP address should be the IP address of your + database server. + </para></listitem> + <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis> + From your + <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. + <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink> + or + <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>). + </para></listitem> + <listitem><para><emphasis>Start 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. + Here is an example that builds the + <filename>core-image-minimal</filename> image: + <literallayout class='monospaced'> + $ bitbake core-image-minimal + </literallayout> + When you are finished with a build in a given + Build Directory, be sure to <filename>kill</filename> + the BitBake server for that build area: + <literallayout class='monospaced'> + $ bitbake -m + </literallayout> + </para></listitem> + </orderedlist> + </para> + + <para> + For information on how to use the Toaster web interface, + see the + "<link linkend='using-the-toaster-web-interface'>Using the Toaster Web Interface</link>" + section. + </para> + </section> + </section> + + <section id='using-toaster-in-build-mode'> + <title>Using Toaster in Build Mode</title> + + <para> + This section describes how to use Toaster in Build Mode + after setting Toaster up as a local instance or as a hosted + service. + </para> + + <section id='setting-up-locally-and-running-in-build-mode'> + <title>Setting Up Locally and Running in Build Mode</title> + + <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>. + 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> + + <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>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 information 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 user, which is "poky" in this example. + 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> + <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>Download the hosted <filename>toasterconf.json</filename> file</ulink> + from the Yocto Project wiki 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> + <para>After editing the file, load it by running + the following: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py loadconf path-to-toasterconf.json-file + </literallayout> + For reference information on Toaster-specific + <filename>manage.py</filename>, see the + "<link linkend='toaster-useful-commands'>Useful Commands</link>" + section. + </para></listitem> + <listitem><para><emphasis>Check the Toaster Settings:</emphasis> + Configure the build environment by running the + following: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py checksettings + </literallayout> + When prompted, paste in the directory paths created + previously during Step 7. + For reference information on Toaster-specific + <filename>manage.py</filename>, see the + "<link linkend='toaster-useful-commands'>Useful Commands</link>" + section. + </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 + <ulink url='https://docs.djangoproject.com/en/1.7/howto/deployment/wsgi/'><filename>django</filename> WSGI</ulink>. + 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: + <literallayout class='monospaced'> + http://localhost:8000/toastergui + </literallayout> + You can track accesses and errors in the Apache + service logs. + </para></listitem> + </orderedlist> + </para> + </section> + </section> + + <section id='using-the-toaster-web-interface'> + <title>Using the Toaster Web Interface</title> + + <para> + The Toaster web interface allows you to do the following: + <itemizedlist> + <listitem><para> + Browse published layers in the + <ulink url='http://layers.openembedded.org'>OpenEmbedded Metadata Index</ulink> + that are available for your selected version of the build + system. + </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> + <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> + Following are several videos that show how to use the Toaster GUI: + <itemizedlist> + <listitem><para><emphasis>Build Configuration:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=qYgDZ8YzV6w'>video</ulink> + overviews and demonstrates build configuration for Toaster. + </para></listitem> + <listitem><para><emphasis>Toaster Homepage and Table Controls:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=QEARDnrR1Xw'>video</ulink> + 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. + </para></listitem> + <listitem><para><emphasis>Build Dashboard:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=KKqHYcnp2gE'>video</ulink> + shows you the build dashboard, a page providing an + overview of the information available for a selected build. + </para></listitem> + <listitem><para><emphasis>Image Information:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=XqYGFsmA0Rw'>video</ulink> + walks through the information Toaster provides + about images: packages installed and root file system. + </para></listitem> + <listitem><para><emphasis>Configuration:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=UW-j-T2TzIg'>video</ulink> + provides Toaster build configuration information. + </para></listitem> + <listitem><para><emphasis>Tasks:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=D4-9vGSxQtw'>video</ulink> + shows the information Toaster provides about the + tasks run by the build system. + </para></listitem> + <listitem><para><emphasis>Recipes and Packages Built:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=x-6dx4huNnw'>video</ulink> + shows the information Toaster provides about recipes + and packages built. + </para></listitem> + <listitem><para><emphasis>Performance Data:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=qWGMrJoqusQ'>video</ulink> + shows the build performance data provided by + Toaster. + </para></listitem> + </itemizedlist> + </para> + </section> + +<!-- + <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>qYgDZ8YzV6w + </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> +--> +</chapter> diff --git a/documentation/toaster-manual/toaster-manual-start.xml b/documentation/toaster-manual/toaster-manual-start.xml new file mode 100644 index 0000000000..65340a1b5e --- /dev/null +++ b/documentation/toaster-manual/toaster-manual-start.xml @@ -0,0 +1,141 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<chapter id='toaster-manual-start'> + +<title>Preparing to Use Toaster</title> + + <para> + This chapter describes how you need to prepare your system in order to + use Toaster. + </para> + + <section id='toaster-setting-up-the-basic-system-requirements'> + <title>Setting Up the Basic System Requirements</title> + + <para> + You first need to be sure your build system is set up to run + the Yocto Project. + See the + "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" + section in the Yocto Project Quick Start for information on how + to set up your system for the Yocto Project. + </para> + </section> + + <section id='toaster-establishing-toaster-system-dependencies'> + <title>Establishing Toaster System Dependencies</title> + + <para> + Toaster requires extra Python dependencies 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> + (e.g. <filename>poky/bitbake/toaster-requirements.txt</filename>). + The dependencies appear in a <filename>pip</filename>, + 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> + </orderedlist> + <note> + If you do choose to set up a virtual environment in + which to run Toaster, you must initialize that + virtual environment each time you want to start + Toaster. + Use the following to initialize the environment just + before you start Toaster: + <literallayout class='monospaced'> + $ source venv/bin/activate + </literallayout> + </note> + </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> + </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-style.css b/documentation/toaster-manual/toaster-manual-style.css new file mode 100644 index 0000000000..6d6b9fb65d --- /dev/null +++ b/documentation/toaster-manual/toaster-manual-style.css @@ -0,0 +1,984 @@ +/* + Generic XHTML / DocBook XHTML CSS Stylesheet. + + Browser wrangling and typographic design by + Oyvind Kolas / pippin@gimp.org + + Customised for Poky by + Matthew Allum / mallum@o-hand.com + + Thanks to: + Liam R. E. Quin + William Skaggs + Jakub Steiner + + Structure + --------- + + The stylesheet is divided into the following sections: + + Positioning + Margins, paddings, width, font-size, clearing. + Decorations + Borders, style + Colors + Colors + Graphics + Graphical backgrounds + Nasty IE tweaks + Workarounds needed to make it work in internet explorer, + currently makes the stylesheet non validating, but up until + this point it is validating. + Mozilla extensions + Transparency for footer + Rounded corners on boxes + +*/ + + + /*************** / + / Positioning / +/ ***************/ + +body { + font-family: Verdana, Sans, sans-serif; + + min-width: 640px; + width: 80%; + margin: 0em auto; + padding: 2em 5em 5em 5em; + color: #333; +} + +h1,h2,h3,h4,h5,h6,h7 { + font-family: Arial, Sans; + color: #00557D; + clear: both; +} + +h1 { + font-size: 2em; + text-align: left; + padding: 0em 0em 0em 0em; + margin: 2em 0em 0em 0em; +} + +h2.subtitle { + margin: 0.10em 0em 3.0em 0em; + padding: 0em 0em 0em 0em; + font-size: 1.8em; + padding-left: 20%; + font-weight: normal; + font-style: italic; +} + +h2 { + margin: 2em 0em 0.66em 0em; + padding: 0.5em 0em 0em 0em; + font-size: 1.5em; + font-weight: bold; +} + +h3.subtitle { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; + font-size: 142.14%; + text-align: right; +} + +h3 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 140%; + font-weight: bold; +} + +h4 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 120%; + font-weight: bold; +} + +h5 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +h6 { + margin: 1em 0em 0em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +.authorgroup { + background-color: transparent; + background-repeat: no-repeat; + padding-top: 256px; + background-image: url("figures/toaster-title.png"); + background-position: left top; + margin-top: -256px; + padding-right: 50px; + margin-left: 0px; + text-align: right; + width: 740px; +} + +h3.author { + margin: 0em 0me 0em 0em; + padding: 0em 0em 0em 0em; + font-weight: normal; + font-size: 100%; + color: #333; + clear: both; +} + +.author tt.email { + font-size: 66%; +} + +.titlepage hr { + width: 0em; + clear: both; +} + +.revhistory { + padding-top: 2em; + clear: both; +} + +.toc, +.list-of-tables, +.list-of-examples, +.list-of-figures { + padding: 1.33em 0em 2.5em 0em; + color: #00557D; +} + +.toc p, +.list-of-tables p, +.list-of-figures p, +.list-of-examples p { + padding: 0em 0em 0em 0em; + padding: 0em 0em 0.3em; + margin: 1.5em 0em 0em 0em; +} + +.toc p b, +.list-of-tables p b, +.list-of-figures p b, +.list-of-examples p b{ + font-size: 100.0%; + font-weight: bold; +} + +.toc dl, +.list-of-tables dl, +.list-of-figures dl, +.list-of-examples dl { + margin: 0em 0em 0.5em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dt { + margin: 0em 0em 0em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dd { + margin: 0em 0em 0em 2.6em; + padding: 0em 0em 0em 0em; +} + +div.glossary dl, +div.variablelist dl { +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + font-weight: normal; + width: 20em; + text-align: right; +} + +.variablelist dl dt { + margin-top: 0.5em; +} + +.glossary dl dd, +.variablelist dl dd { + margin-top: -1em; + margin-left: 25.5em; +} + +.glossary dd p, +.variablelist dd p { + margin-top: 0em; + margin-bottom: 1em; +} + + +div.calloutlist table td { + padding: 0em 0em 0em 0em; + margin: 0em 0em 0em 0em; +} + +div.calloutlist table td p { + margin-top: 0em; + margin-bottom: 1em; +} + +div p.copyright { + text-align: left; +} + +div.legalnotice p.legalnotice-title { + margin-bottom: 0em; +} + +p { + line-height: 1.5em; + margin-top: 0em; + +} + +dl { + padding-top: 0em; +} + +hr { + border: solid 1px; +} + + +.mediaobject, +.mediaobjectco { + text-align: center; +} + +img { + border: none; +} + +ul { + padding: 0em 0em 0em 1.5em; +} + +ul li { + padding: 0em 0em 0em 0em; +} + +ul li p { + text-align: left; +} + +table { + width :100%; +} + +th { + padding: 0.25em; + text-align: left; + font-weight: normal; + vertical-align: top; +} + +td { + padding: 0.25em; + vertical-align: top; +} + +p a[id] { + margin: 0px; + padding: 0px; + display: inline; + background-image: none; +} + +a { + text-decoration: underline; + color: #444; +} + +pre { + overflow: auto; +} + +a:hover { + text-decoration: underline; + /*font-weight: bold;*/ +} + +/* This style defines how the permalink character + appears by itself and when hovered over with + the mouse. */ + +[alt='Permalink'] { color: #eee; } +[alt='Permalink']:hover { color: black; } + + +div.informalfigure, +div.informalexample, +div.informaltable, +div.figure, +div.table, +div.example { + margin: 1em 0em; + padding: 1em; + page-break-inside: avoid; +} + + +div.informalfigure p.title b, +div.informalexample p.title b, +div.informaltable p.title b, +div.figure p.title b, +div.example p.title b, +div.table p.title b{ + padding-top: 0em; + margin-top: 0em; + font-size: 100%; + font-weight: normal; +} + +.mediaobject .caption, +.mediaobject .caption p { + text-align: center; + font-size: 80%; + padding-top: 0.5em; + padding-bottom: 0.5em; +} + +.epigraph { + padding-left: 55%; + margin-bottom: 1em; +} + +.epigraph p { + text-align: left; +} + +.epigraph .quote { + font-style: italic; +} +.epigraph .attribution { + font-style: normal; + text-align: right; +} + +span.application { + font-style: italic; +} + +.programlisting { + font-family: monospace; + font-size: 80%; + white-space: pre; + margin: 1.33em 0em; + padding: 1.33em; +} + +.tip, +.warning, +.caution, +.note { + margin-top: 1em; + margin-bottom: 1em; + +} + +/* force full width of table within div */ +.tip table, +.warning table, +.caution table, +.note table { + border: none; + width: 100%; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + padding: 0.8em 0.0em 0.0em 0.0em; + margin : 0em 0em 0em 0em; +} + +.tip p, +.warning p, +.caution p, +.note p { + margin-top: 0.5em; + margin-bottom: 0.5em; + padding-right: 1em; + text-align: left; +} + +.acronym { + text-transform: uppercase; +} + +b.keycap, +.keycap { + padding: 0.09em 0.3em; + margin: 0em; +} + +.itemizedlist li { + clear: none; +} + +.filename { + font-size: medium; + font-family: Courier, monospace; +} + + +div.navheader, div.heading{ + position: absolute; + left: 0em; + top: 0em; + width: 100%; + background-color: #cdf; + width: 100%; +} + +div.navfooter, div.footing{ + position: fixed; + left: 0em; + bottom: 0em; + background-color: #eee; + width: 100%; +} + + +div.navheader td, +div.navfooter td { + font-size: 66%; +} + +div.navheader table th { + /*font-family: Georgia, Times, serif;*/ + /*font-size: x-large;*/ + font-size: 80%; +} + +div.navheader table { + border-left: 0em; + border-right: 0em; + border-top: 0em; + width: 100%; +} + +div.navfooter table { + border-left: 0em; + border-right: 0em; + border-bottom: 0em; + width: 100%; +} + +div.navheader table td a, +div.navfooter table td a { + color: #777; + text-decoration: none; +} + +/* normal text in the footer */ +div.navfooter table td { + color: black; +} + +div.navheader table td a:visited, +div.navfooter table td a:visited { + color: #444; +} + + +/* links in header and footer */ +div.navheader table td a:hover, +div.navfooter table td a:hover { + text-decoration: underline; + background-color: transparent; + color: #33a; +} + +div.navheader hr, +div.navfooter hr { + display: none; +} + + +.qandaset tr.question td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} + +.qandaset tr.answer td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} +.answer td { + padding-bottom: 1.5em; +} + +.emphasis { + font-weight: bold; +} + + + /************* / + / decorations / +/ *************/ + +.titlepage { +} + +.part .title { +} + +.subtitle { + border: none; +} + +/* +h1 { + border: none; +} + +h2 { + border-top: solid 0.2em; + border-bottom: solid 0.06em; +} + +h3 { + border-top: 0em; + border-bottom: solid 0.06em; +} + +h4 { + border: 0em; + border-bottom: solid 0.06em; +} + +h5 { + border: 0em; +} +*/ + +.programlisting { + border: solid 1px; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example { + border: 1px solid; +} + + + +.tip, +.warning, +.caution, +.note { + border: 1px solid; +} + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom: 1px solid; +} + +.question td { + border-top: 1px solid black; +} + +.answer { +} + + +b.keycap, +.keycap { + border: 1px solid; +} + + +div.navheader, div.heading{ + border-bottom: 1px solid; +} + + +div.navfooter, div.footing{ + border-top: 1px solid; +} + + /********* / + / colors / +/ *********/ + +body { + color: #333; + background: white; +} + +a { + background: transparent; +} + +a:hover { + background-color: #dedede; +} + + +h1, +h2, +h3, +h4, +h5, +h6, +h7, +h8 { + background-color: transparent; +} + +hr { + border-color: #aaa; +} + + +.tip, .warning, .caution, .note { + border-color: #fff; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom-color: #fff; +} + + +.warning { + background-color: #f0f0f2; +} + +.caution { + background-color: #f0f0f2; +} + +.tip { + background-color: #f0f0f2; +} + +.note { + background-color: #f0f0f2; +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + color: #044; +} + +div.figure, +div.table, +div.example, +div.informalfigure, +div.informaltable, +div.informalexample { + border-color: #aaa; +} + +pre.programlisting { + color: black; + background-color: #fff; + border-color: #aaa; + border-width: 2px; +} + +.guimenu, +.guilabel, +.guimenuitem { + background-color: #eee; +} + + +b.keycap, +.keycap { + background-color: #eee; + border-color: #999; +} + + +div.navheader { + border-color: black; +} + + +div.navfooter { + border-color: black; +} + + + /*********** / + / graphics / +/ ***********/ + +/* +body { + background-image: url("images/body_bg.jpg"); + background-attachment: fixed; +} + +.navheader, +.note, +.tip { + background-image: url("images/note_bg.jpg"); + background-attachment: fixed; +} + +.warning, +.caution { + background-image: url("images/warning_bg.jpg"); + background-attachment: fixed; +} + +.figure, +.informalfigure, +.example, +.informalexample, +.table, +.informaltable { + background-image: url("images/figure_bg.jpg"); + background-attachment: fixed; +} + +*/ +h1, +h2, +h3, +h4, +h5, +h6, +h7{ +} + +/* +Example of how to stick an image as part of the title. + +div.article .titlepage .title +{ + background-image: url("figures/white-on-black.png"); + background-position: center; + background-repeat: repeat-x; +} +*/ + +div.preface .titlepage .title, +div.colophon .title, +div.chapter .titlepage .title, +div.article .titlepage .title +{ +} + +div.section div.section .titlepage .title, +div.sect2 .titlepage .title { + background: none; +} + + +h1.title { + background-color: transparent; + background-repeat: no-repeat; + height: 256px; + text-indent: -9000px; + overflow:hidden; +} + +h2.subtitle { + background-color: transparent; + text-indent: -9000px; + overflow:hidden; + width: 0px; + display: none; +} + + /*************************************** / + / pippin.gimp.org specific alterations / +/ ***************************************/ + +/* +div.heading, div.navheader { + color: #777; + font-size: 80%; + padding: 0; + margin: 0; + text-align: left; + position: absolute; + top: 0px; + left: 0px; + width: 100%; + height: 50px; + background: url('/gfx/heading_bg.png') transparent; + background-repeat: repeat-x; + background-attachment: fixed; + border: none; +} + +div.heading a { + color: #444; +} + +div.footing, div.navfooter { + border: none; + color: #ddd; + font-size: 80%; + text-align:right; + + width: 100%; + padding-top: 10px; + position: absolute; + bottom: 0px; + left: 0px; + + background: url('/gfx/footing_bg.png') transparent; +} +*/ + + + + /****************** / + / nasty ie tweaks / +/ ******************/ + +/* +div.heading, div.navheader { + width:expression(document.body.clientWidth + "px"); +} + +div.footing, div.navfooter { + width:expression(document.body.clientWidth + "px"); + margin-left:expression("-5em"); +} +body { + padding:expression("4em 5em 0em 5em"); +} +*/ + + /**************************************** / + / mozilla vendor specific css extensions / +/ ****************************************/ +/* +div.navfooter, div.footing{ + -moz-opacity: 0.8em; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example, +.tip, +.warning, +.caution, +.note { + -moz-border-radius: 0.5em; +} + +b.keycap, +.keycap { + -moz-border-radius: 0.3em; +} +*/ + +table tr td table tr td { + display: none; +} + + +hr { + display: none; +} + +table { + border: 0em; +} + + .photo { + float: right; + margin-left: 1.5em; + margin-bottom: 1.5em; + margin-top: 0em; + max-width: 17em; + border: 1px solid gray; + padding: 3px; + background: white; +} + .seperator { + padding-top: 2em; + clear: both; + } + + #validators { + margin-top: 5em; + text-align: right; + color: #777; + } + @media print { + body { + font-size: 8pt; + } + .noprint { + display: none; + } + } + + +.tip, +.note { + background: #f0f0f2; + color: #333; + padding: 20px; + margin: 20px; +} + +.tip h3, +.note h3 { + padding: 0em; + margin: 0em; + font-size: 2em; + font-weight: bold; + color: #333; +} + +.tip a, +.note a { + color: #333; + text-decoration: underline; +} + +.footnote { + font-size: small; + color: #333; +} + +/* Changes the announcement text */ +.tip h3, +.warning h3, +.caution h3, +.note h3 { + font-size:large; + color: #00557D; +} diff --git a/documentation/toaster-manual/toaster-manual.xml b/documentation/toaster-manual/toaster-manual.xml new file mode 100644 index 0000000000..f3cc8850bd --- /dev/null +++ b/documentation/toaster-manual/toaster-manual.xml @@ -0,0 +1,73 @@ +<!DOCTYPE book 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; ] > + +<book id='toaster-manual' lang='en' + xmlns:xi="http://www.w3.org/2003/XInclude" + xmlns="http://docbook.org/ns/docbook" + > + <bookinfo> + + <mediaobject> + <imageobject> + <imagedata fileref='figures/toaster-title.png' + format='SVG' + align='left' scalefit='1' width='100%'/> + </imageobject> + </mediaobject> + + <title> + Toaster User Manual + </title> + + <authorgroup> + <author> + <firstname>Scott</firstname> <surname>Rifenbark</surname> + <affiliation> + <orgname>Intel Corporation</orgname> + </affiliation> + <email>scott.m.rifenbark@intel.com</email> + </author> + </authorgroup> + + <revhistory> + <revision> + <revnumber>1.8</revnumber> + <date>April 2015</date> + <revremark>Released with the Yocto Project 1.8 Release.</revremark> + </revision> + </revhistory> + + <copyright> + <year>©RIGHT_YEAR;</year> + <holder>Linux Foundation</holder> + </copyright> + + <legalnotice> + <para> + Permission is granted to copy, distribute and/or modify this document under + the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. + </para> + <note> + For the latest version of this manual associated with this + Yocto Project release, see the + <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink> + from the Yocto Project website. + </note> + + </legalnotice> + + </bookinfo> + + <xi:include href="toaster-manual-intro.xml"/> + + <xi:include href="toaster-manual-start.xml"/> + + <xi:include href="toaster-manual-setup-and-use.xml"/> + + <xi:include href="toaster-manual-reference.xml"/> + +</book> +<!-- +vim: expandtab tw=80 ts=4 +--> |
