mirror of
git://git.yoctoproject.org/poky.git
synced 2025-07-19 21:09:03 +02:00
5ecdd8ef46
Changed some wordings to accomodate reviewer feedback. (From yocto-docs rev: 6de69db7ae5bbbe5e6e7f0b5f6b9b1326f3f5f6a) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
844 lines
38 KiB
XML
844 lines
38 KiB
XML
<!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='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>
|