Revert "poky: subtree update:b23aa6b753..ad30a6d470"
This reverts commit af5e4ef732faedf66c6dc1756432e9de2ac72988.
This commit introduced openbmc/openbmc#3720 and no solution has been
forthcoming. Revert until we can get to the bottom of this.
Change-Id: I2fb0d81eb26cf3dadb2f2abdd1a1bb7a95eaf03c
diff --git a/poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml
new file mode 100644
index 0000000..f555745
--- /dev/null
+++ b/poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml
@@ -0,0 +1,844 @@
+<!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; ] >
+<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
+
+<chapter id='toaster-manual-setup-and-use'>
+
+<title>Setting Up and Using Toaster</title>
+
+ <section id='starting-toaster-for-local-development'>
+ <title>Starting Toaster for Local Development</title>
+
+ <para>
+ Once you have set up the Yocto Project and installed the
+ Toaster system dependencies as described in the
+ "<link linkend='toaster-manual-start'>Preparing to Use Toaster</link>"
+ chapter, you are ready to start Toaster.
+ </para>
+
+ <para>
+ Navigate to the root of your
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ (e.g. <filename>poky</filename>):
+ <literallayout class='monospaced'>
+ $ cd poky
+ </literallayout>
+ Once in that directory, source the build environment script:
+ <literallayout class='monospaced'>
+ $ source oe-init-build-env
+ </literallayout>
+ Next, from the build directory (e.g.
+ <filename>poky/build</filename>), start Toaster using this
+ command:
+ <literallayout class='monospaced'>
+ $ source toaster start
+ </literallayout>
+ You can now run your builds from the command line, or with
+ Toaster as explained in section
+ "<link linkend='using-the-toaster-web-interface'>Using the Toaster Web Interface</link>".
+ </para>
+
+ <para>
+ To access the Toaster web interface, open your favorite
+ browser and enter the following:
+ <literallayout class='monospaced'>
+ http://127.0.0.1:8000
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='setting-a-different-port'>
+ <title>Setting a Different Port</title>
+
+ <para>
+ By default, Toaster starts on port 8000.
+ You can use the <filename>WEBPORT</filename> parameter to
+ set a different port.
+ For example, the following command sets the port to "8400":
+ <literallayout class='monospaced'>
+ $ source toaster start webport=8400
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='setting-up-toaster-without-a-web-server'>
+ <title>Setting Up Toaster Without a Web Server</title>
+
+ <para>
+ You can start a Toaster environment without starting its
+ web server. This is useful for the following:
+ <itemizedlist>
+ <listitem><para>
+ Capturing a command-line build's statistics into
+ the Toaster database for examination later.
+ </para></listitem>
+ <listitem><para>
+ Capturing a command-line build's statistics when
+ the Toaster server is already running.
+ </para></listitem>
+ <listitem><para>
+ Having one instance of the Toaster web server
+ track and capture multiple command-line builds,
+ where each build is started in its own "noweb"
+ Toaster environment.
+ </para></listitem>
+ </itemizedlist>
+ The following commands show how to start a Toaster environment
+ without starting its web server, perform BitBake operations,
+ and then shut down the Toaster environment.
+ Once the build is complete, you can close the Toaster environment.
+ Before closing the environment, however, you should allow a few
+ minutes to ensure the complete transfer of its BitBake build
+ statistics to the Toaster database.
+ If you have a separate Toaster web server instance running, you
+ can watch this command-line build's progress and examine the
+ results as soon as they are posted:
+ <literallayout class='monospaced'>
+ $ source toaster start noweb
+ $ bitbake <replaceable>target</replaceable>
+ $ source toaster stop
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='setting-up-toaster-without-a-build-server'>
+ <title>Setting Up Toaster Without a Build Server</title>
+
+ <para>
+ You can start a Toaster environment with the
+ "New Projects" feature disabled.
+ Doing so is useful for the following:
+ <itemizedlist>
+ <listitem><para>
+ Sharing your build results over the web server while
+ blocking others from starting builds on your host.
+ </para></listitem>
+ <listitem><para>
+ Allowing only local command-line builds to be captured
+ into the Toaster database.
+ </para></listitem>
+ </itemizedlist>
+ Use the following command to set up Toaster without a
+ build server:
+ <literallayout class='monospaced'>
+ $ source toaster start nobuild webport=<replaceable>port</replaceable>
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='setting-up-external-access'>
+ <title>Setting up External Access</title>
+
+ <para>
+ By default, Toaster binds to the loop back address
+ (i.e. localhost), which does not allow access from
+ external hosts. To allow external access, use the
+ <filename>WEBPORT</filename> parameter to open an
+ address that connects to the network, specifically the
+ IP address that your NIC uses to connect to the network.
+ You can also bind to all IP addresses the computer
+ supports by using the shortcut
+ "0.0.0.0:<replaceable>port</replaceable>".
+ </para>
+
+ <para>
+ The following example binds to all IP addresses on the
+ host:
+ <literallayout class='monospaced'>
+ $ source toaster start webport=0.0.0.0:8400
+ </literallayout>
+ This example binds to a specific IP address on the host's
+ NIC:
+ <literallayout class='monospaced'>
+ $ source toaster start webport=192.168.1.1:8400
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='the-directory-for-cloning-layers'>
+ <title>The Directory for Cloning Layers</title>
+
+ <para>
+ Toaster creates a <filename>_toaster_clones</filename>
+ directory inside your Source Directory
+ (i.e. <filename>poky</filename>) to clone any layers
+ needed for your builds.
+ </para>
+
+ <para>
+ Alternatively, if you would like all of your Toaster related
+ files and directories to be in a particular location other than
+ the default, you can set the <filename>TOASTER_DIR</filename>
+ environment variable, which takes precedence over your current
+ working directory.
+ Setting this environment variable causes Toaster to create and use
+ <filename>$TOASTER_DIR./_toaster_clones</filename>.
+ </para>
+ </section>
+
+ <section id='toaster-the-build-directory'>
+ <title>The Build Directory</title>
+
+ <para>
+ Toaster creates a build directory within your Source
+ Directory (e.g. <filename>poky</filename>) to execute
+ the builds.
+ </para>
+
+ <para>
+ Alternatively, if you would like all of your Toaster related files
+ and directories to be in a particular location, you can set
+ the <filename>TOASTER_DIR</filename> environment variable,
+ which takes precedence over your current working directory.
+ Setting this environment variable causes Toaster to use
+ <filename>$TOASTER_DIR/build</filename> as the build directory.
+ </para>
+ </section>
+
+ <section id='toaster-creating-a-django-super-user'>
+ <title>Creating a Django Superuser</title>
+
+ <para>
+ Toaster is built on the
+ <ulink url='https://www.djangoproject.com/'>Django framework</ulink>.
+ Django provides an administration interface you can use
+ to edit Toaster configuration parameters.
+ </para>
+
+ <para>
+ To access the Django administration interface, you must
+ create a superuser by following these steps:
+ <orderedlist>
+ <listitem><para>
+ If you used <filename>pip3</filename>, which is
+ recommended, to set up the Toaster system dependencies,
+ you need be sure the local user path is in your
+ <filename>PATH</filename> list.
+ To append the pip3 local user path, use the following
+ command:
+ <literallayout class='monospaced'>
+ $ export PATH=$PATH:$HOME/.local/bin
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ From the directory containing the Toaster database,
+ which by default is the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
+ invoke the <filename>createsuperuser</filename> command
+ from <filename>manage.py</filename>:
+ <literallayout class='monospaced'>
+ $ cd ~/poky/build
+ $ ../bitbake/lib/toaster/manage.py createsuperuser
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Django prompts you for the username, which you need to
+ provide.
+ </para></listitem>
+ <listitem><para>
+ Django prompts you for an email address, which is
+ optional.
+ </para></listitem>
+ <listitem><para>
+ Django prompts you for a password, which you must provide.
+ </para></listitem>
+ <listitem><para>
+ Django prompts you to re-enter your password for verification.
+ </para></listitem>
+ </orderedlist>
+ After completing these steps, the following confirmation message
+ appears:
+ <literallayout class='monospaced'>
+ Superuser created successfully.
+ </literallayout>
+ </para>
+
+ <para>
+ Creating a superuser allows you to access the Django administration
+ interface through a browser.
+ The URL for this interface is the same as the URL used for the
+ Toaster instance with "/admin" on the end.
+ For example, if you are running Toaster locally, use the
+ following URL:
+ <literallayout class='monospaced'>
+ http://127.0.0.1:8000/admin
+ </literallayout>
+ You can use the Django administration interface to set Toaster
+ configuration parameters such as the build directory, layer sources,
+ default variable values, and BitBake versions.
+ </para>
+ </section>
+
+ <section id='toaster-setting-up-a-production-instance-of-toaster'>
+ <title>Setting Up a Production Instance of Toaster</title>
+
+ <para>
+ You can use a production instance of Toaster to share the
+ Toaster instance with remote users, multiple users, or both.
+ The production instance is also the setup that can handle
+ heavier loads on the web service.
+ Use the instructions in the following sections to set up
+ Toaster to run builds through the Toaster web interface.
+ </para>
+
+ <section id='toaster-production-instance-requirements'>
+ <title>Requirements</title>
+
+ <para>
+ Be sure you meet the following requirements:
+ <note>
+ You must comply with all Apache,
+ <filename>mod-wsgi</filename>, and Mysql requirements.
+ </note>
+ <itemizedlist>
+ <listitem><para>
+ Have all the build requirements as described in the
+ "<link linkend='toaster-manual-start'>Preparing to Use Toaster</link>"
+ chapter.
+ </para></listitem>
+ <listitem><para>
+ Have an Apache webserver.
+ </para></listitem>
+ <listitem><para>
+ Have <filename>mod-wsgi</filename> for the Apache
+ webserver.
+ </para></listitem>
+ <listitem><para>
+ Use the Mysql database server.
+ </para></listitem>
+ <listitem><para>
+ If you are using Ubuntu 16.04, run the following:
+ <literallayout class='monospaced'>
+ $ sudo apt-get install apache2 libapache2-mod-wsgi-py3 mysql-server python3-pip libmysqlclient-dev
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ If you are using Fedora 24 or a RedHat distribution, run
+ the following:
+ <literallayout class='monospaced'>
+ $ sudo dnf install httpd python3-mod_wsgi python3-pip mariadb-server mariadb-devel python3-devel
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ If you are using openSUSE Leap 42.1, run
+ the following:
+ <literallayout class='monospaced'>
+ $ sudo zypper install apache2 apache2-mod_wsgi-python3 python3-pip mariadb mariadb-client python3-devel
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='toaster-installation-steps'>
+ <title>Installation</title>
+
+ <para>
+ Perform the following steps to install Toaster:
+ <orderedlist>
+ <listitem><para>
+ Create toaster user and set its home directory to
+ <filename>/var/www/toaster</filename>:
+ <literallayout class='monospaced'>
+ $ sudo /usr/sbin/useradd toaster -md /var/www/toaster -s /bin/false
+ $ sudo su - toaster -s /bin/bash
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Checkout a copy of <filename>poky</filename>
+ into the web server directory.
+ You will be using <filename>/var/www/toaster</filename>:
+ <literallayout class='monospaced'>
+ $ git clone git://git.yoctoproject.org/poky
+ $ git checkout &DISTRO_NAME_NO_CAP;
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Install Toaster
+ dependencies using the --user flag which
+ keeps the Python packages
+ isolated from your system-provided packages:
+ <literallayout class='monospaced'>
+ $ cd /var/www/toaster/
+ $ pip3 install --user -r ./poky/bitbake/toaster-requirements.txt
+ $ pip3 install --user mysqlclient
+ </literallayout>
+ <note>
+ Isolating these packages is not required but is
+ recommended.
+ Alternatively, you can use your operating system's
+ package manager to install the packages.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ Configure Toaster by editing
+ <filename>/var/www/toaster/poky/bitbake/lib/toaster/toastermain/settings.py</filename>
+ as follows:
+ <itemizedlist>
+ <listitem><para>
+ Edit the
+ <ulink url='https://docs.djangoproject.com/en/1.11/ref/settings/#databases'>DATABASES</ulink>
+ settings:
+ <literallayout class='monospaced'>
+ DATABASES = {
+ 'default': {
+ 'ENGINE': 'django.db.backends.mysql',
+ 'NAME': 'toaster_data',
+ 'USER': 'toaster',
+ 'PASSWORD': 'yourpasswordhere',
+ 'HOST': 'localhost',
+ 'PORT': '3306',
+ }
+ }
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Edit the
+ <ulink url='https://docs.djangoproject.com/en/1.11/ref/settings/#std:setting-SECRET_KEY'>SECRET_KEY</ulink>:
+ <literallayout class='monospaced'>
+ SECRET_KEY = '<replaceable>your_secret_key</replaceable>'
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Edit the
+ <ulink url='https://docs.djangoproject.com/en/1.11/ref/settings/#std:setting-STATIC_ROOT'>STATIC_ROOT</ulink>:
+ <literallayout class='monospaced'>
+ STATIC_ROOT = '/var/www/toaster/static_files/'
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ Add the database and user to the <filename>mysql</filename>
+ server defined earlier:
+ <literallayout class='monospaced'>
+ $ mysql -u root -p
+ mysql> CREATE DATABASE toaster_data;
+ mysql> CREATE USER 'toaster'@'localhost' identified by 'yourpasswordhere';
+ mysql> GRANT all on toaster_data.* to 'toaster'@'localhost';
+ mysql> quit
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Get Toaster to create the database schema,
+ default data, and gather the statically-served files:
+ <literallayout class='monospaced'>
+ $ cd /var/www/toaster/poky/
+ $ ./bitbake/lib/toaster/manage.py migrate
+ $ TOASTER_DIR=`pwd` TEMPLATECONF='poky' \
+ ./bitbake/lib/toaster/manage.py checksettings
+ $ ./bitbake/lib/toaster/manage.py collectstatic
+ </literallayout>
+ In the previous example, from the <filename>poky</filename>
+ directory, the <filename>migrate</filename> command
+ ensures the database schema changes have propagated
+ correctly (i.e. migrations).
+ The next line sets the Toaster root directory
+ <filename>TOASTER_DIR</filename> and the location
+ of the Toaster configuration file
+ <filename>TOASTER_CONF</filename>, which is relative to
+ <filename>TOASTER_DIR</filename>.
+ The <filename>TEMPLATECONF</filename> value reflects the
+ contents of <filename>poky/.templateconf</filename>, and
+ by default, should include the string "poky".
+ For more information on the Toaster configuration
+ file, see the
+ "<link linkend='configuring-toaster'>Configuring Toaster</link>"
+ section.</para>
+
+ <para>This line also runs the <filename>checksettings</filename>
+ command, which configures the location of the Toaster
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
+ The Toaster root directory <filename>TOASTER_DIR</filename>
+ determines where the Toaster build directory
+ is created on the file system.
+ In the example above,
+ <filename>TOASTER_DIR</filename> is set as follows:
+ <literallayout class="monospaced">
+ /var/www/toaster/poky
+ </literallayout>
+ This setting causes the Toaster build directory to be:
+ <literallayout class="monospaced">
+ /var/www/toaster/poky/build
+ </literallayout></para>
+
+ <para>Finally, the <filename>collectstatic</filename> command
+ is a Django framework command that collects all the
+ statically served files into a designated directory to
+ be served up by the Apache web server as defined by
+ <filename>STATIC_ROOT</filename>.
+ </para></listitem>
+ <listitem><para>
+ Test and/or use the Mysql integration with Toaster's
+ Django web server.
+ At this point, you can start up the normal Toaster
+ Django web server with the Toaster database in Mysql.
+ You can use this web server to confirm that the database
+ migration and data population from the Layer Index is
+ complete.</para>
+
+ <para>To start the default Toaster Django web server with
+ the Toaster database now in Mysql, use the standard
+ start commands:
+ <literallayout class='monospaced'>
+ $ source oe-init-build-env
+ $ source toaster start
+ </literallayout>
+ Additionally, if Django is sufficient for your requirements,
+ you can use it for your release system and migrate later
+ to Apache as your requirements change.
+ </para></listitem>
+ <listitem><para>
+ Add an Apache configuration file for Toaster to your Apache web
+ server's configuration directory.
+ If you are using Ubuntu or Debian, put the file here:
+ <literallayout class='monospaced'>
+ /etc/apache2/conf-available/toaster.conf
+ </literallayout>
+ If you are using Fedora or RedHat, put it here:
+ <literallayout class='monospaced'>
+ /etc/httpd/conf.d/toaster.conf
+ </literallayout>
+ If you are using OpenSUSE, put it here:
+ <literallayout class='monospaced'>
+ /etc/apache2/conf.d/toaster.conf
+ </literallayout>
+ Following is a sample Apache configuration for Toaster
+ you can follow:
+ <literallayout class='monospaced'>
+ Alias /static /var/www/toaster/static_files
+ <Directory /var/www/toaster/static_files>
+ <IfModule mod_access_compat.c>
+ Order allow,deny
+ Allow from all
+ </IfModule>
+ <IfModule !mod_access_compat.c>
+ Require all granted
+ </IfModule>
+ </Directory>
+
+ <Directory /var/www/toaster/poky/bitbake/lib/toaster/toastermain>
+ <Files "wsgi.py">
+ Require all granted
+ </Files>
+ </Directory>
+
+ WSGIDaemonProcess toaster_wsgi python-path=/var/www/toaster/poky/bitbake/lib/toaster:/var/www/toaster/.local/lib/python3.4/site-packages
+
+ WSGIScriptAlias / "/var/www/toaster/poky/bitbake/lib/toaster/toastermain/wsgi.py"
+ <Location />
+ WSGIProcessGroup toaster_wsgi
+ </Location>
+ </literallayout>
+ If you are using Ubuntu or Debian,
+ you will need to enable the config and module for Apache:
+ <literallayout class='monospaced'>
+ $ sudo a2enmod wsgi
+ $ sudo a2enconf toaster
+ $ chmod +x bitbake/lib/toaster/toastermain/wsgi.py
+ </literallayout>
+ Finally, restart Apache to make sure all new configuration
+ is loaded.
+ For Ubuntu, Debian, and OpenSUSE use:
+ <literallayout class='monospaced'>
+ $ sudo service apache2 restart
+ </literallayout>
+ For Fedora and RedHat use:
+ <literallayout class='monospaced'>
+ $ sudo service httpd restart
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Prepare the systemd service to run Toaster builds.
+ Here is a sample configuration file for the service:
+ <literallayout class='monospaced'>
+ [Unit]
+ Description=Toaster runbuilds
+
+ [Service]
+ Type=forking
+ User=toaster
+ ExecStart=/usr/bin/screen -d -m -S runbuilds /var/www/toaster/poky/bitbake/lib/toaster/runbuilds-service.sh start
+ ExecStop=/usr/bin/screen -S runbuilds -X quit
+ WorkingDirectory=/var/www/toaster/poky
+
+ [Install]
+ WantedBy=multi-user.target
+ </literallayout>
+ Prepare the <filename>runbuilds-service.sh</filename>
+ script that you need to place in the
+ <filename>/var/www/toaster/poky/bitbake/lib/toaster/</filename>
+ directory by setting up executable permissions:
+ <literallayout class='monospaced'>
+ #!/bin/bash
+
+ #export http_proxy=http://proxy.host.com:8080
+ #export https_proxy=http://proxy.host.com:8080
+ #export GIT_PROXY_COMMAND=$HOME/bin/gitproxy
+
+ cd ~/poky/
+ source ./oe-init-build-env build
+ source ../bitbake/bin/toaster $1 noweb
+ [ "$1" == 'start' ] && /bin/bash
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Run the service:
+ <literallayout class='monospaced'>
+ # service runbuilds start
+ </literallayout>
+ Since the service is running in a detached screen
+ session, you can attach to it using this command:
+ <literallayout class='monospaced'>
+ $ sudo su - toaster
+ $ screen -rS runbuilds
+ </literallayout>
+ You can detach from the service again using "Ctrl-a"
+ followed by "d" key combination.
+ </para></listitem>
+ </orderedlist>
+ You can now open up a browser and start using Toaster.
+ </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 Layer 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>
+ </para>
+
+ <section id='web-interface-videos'>
+ <title>Toaster Web Interface Videos</title>
+
+ <para>
+ 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>Build Custom Layers:</emphasis>
+ This
+ <ulink url='https://www.youtube.com/watch?v=QJzaE_XjX5c'>video</ulink>
+ shows you how to build custom layers that are used with
+ 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='a-note-on-the-local-yocto-project-release'>
+ <title>Additional Information About the Local Yocto Project Release</title>
+
+ <para>
+ This section only applies if you have set up Toaster
+ for local development, as explained in the
+ "<link linkend='starting-toaster-for-local-development'>Starting Toaster for Local Development</link>"
+ section.
+ </para>
+
+ <para>
+ When you create a project in Toaster, you will be asked to
+ provide a name and to select a Yocto Project release.
+ One of the release options you will find is called
+ "Local Yocto Project".
+ <imagedata fileref="figures/new-project.png" align="center" width="9in" />
+ </para>
+
+ <para>
+ When you select the "Local Yocto Project" release, Toaster
+ will run your builds using the local Yocto
+ Project clone you have in your computer: the same clone
+ you are using to run Toaster.
+ Unless you manually update
+ this clone, your builds will always use the same Git revision.
+ </para>
+
+ <para>
+ If you select any of the other release options, Toaster
+ will fetch the tip of your selected release from the upstream
+ <ulink url='https://git.yoctoproject.org'>Yocto Project repository</ulink>
+ every time you run a build.
+ Fetching this tip effectively
+ means that if your selected release is updated upstream, the
+ Git revision you are using for your builds will change.
+ If you are doing development locally, you might not want this
+ change to happen.
+ In that case, the "Local Yocto Project"
+ release might be the right choice.
+ </para>
+
+ <para>
+ However, the "Local Yocto Project" release
+ will not provide you with any compatible layers, other than the
+ three core layers that come with the Yocto Project:
+ <itemizedlist>
+ <listitem><para>
+ <ulink url='http://layers.openembedded.org/layerindex/branch/master/layer/openembedded-core/'>openembedded-core</ulink>
+ </para></listitem>
+ <listitem><para>
+ <ulink url='http://layers.openembedded.org/layerindex/branch/master/layer/meta-poky/'>meta-poky</ulink>
+ </para></listitem>
+ <listitem><para>
+ <ulink url='http://layers.openembedded.org/layerindex/branch/master/layer/meta-yocto-bsp/'>meta-yocto-bsp</ulink>
+ </para></listitem>
+ </itemizedlist>
+ <imagedata fileref="figures/compatible-layers.png" align="center" width="9in" />
+ </para>
+
+ <para>
+ If you want to build any other layers, you will need to
+ manually import them into your Toaster project, using the
+ "Import layer" page.
+ <imagedata fileref="figures/import-layer.png" align="center" width="9in" />
+ </para>
+
+ </section>
+
+ <section id='toaster-web-interface-preferred-version'>
+ <title>Building a Specific Recipe Given Multiple Versions</title>
+
+ <para>
+ Occasionally, a layer might provide more than one version of
+ the same recipe.
+ For example, the <filename>openembedded-core</filename> layer
+ provides two versions of the <filename>bash</filename> recipe
+ (i.e. 3.2.48 and 4.3.30-r0) and two versions of the
+ <filename>which</filename> recipe (i.e. 2.21 and 2.18).
+ The following figure shows this exact scenario:
+ <imagedata fileref="figures/bash-oecore.png" align="center" width="9in" depth="6in" />
+ </para>
+
+ <para>
+ By default, the OpenEmbedded build system builds one of the
+ two recipes.
+ For the <filename>bash</filename> case, version 4.3.30-r0 is
+ built by default.
+ Unfortunately, Toaster as it exists, is not able to override
+ the default recipe version.
+ If you would like to build bash 3.2.48, you need to set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink>
+ variable.
+ You can do so from Toaster, using the "Add variable" form,
+ which is available in the "BitBake variables" page of the
+ project configuration section as shown in the following screen:
+ <imagedata fileref="figures/add-variable.png" align="center" width="9in" depth="6in" />
+ </para>
+
+ <para>
+ To specify <filename>bash</filename> 3.2.48 as the version to build,
+ enter "PREFERRED_VERSION_bash" in the "Variable" field, and "3.2.48"
+ in the "Value" field.
+ Next, click the "Add variable" button:
+ <imagedata fileref="figures/set-variable.png" align="center" width="9in" depth="6in" />
+ </para>
+
+ <para>
+ After clicking the "Add variable" button, the settings for
+ <filename>PREFERRED_VERSION</filename> are added to the bottom
+ of the BitBake variables list.
+ With these settings, the OpenEmbedded build system builds the
+ desired version of the recipe rather than the default version:
+ <imagedata fileref="figures/variable-added.png" align="center" width="9in" depth="6in" />
+ </para>
+ </section>
+ </section>
+</chapter>