diff options
Diffstat (limited to 'poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml')
| -rw-r--r-- | poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml | 843 |
1 files changed, 843 insertions, 0 deletions
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 000000000..b4caebbe0 --- /dev/null +++ b/poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml @@ -0,0 +1,843 @@ +<!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> |
