diff --git a/documentation/toaster-manual/figures/compatible-layers.png b/documentation/toaster-manual/figures/compatible-layers.png
new file mode 100644
index 0000000000..38436b075c
Binary files /dev/null and b/documentation/toaster-manual/figures/compatible-layers.png differ
diff --git a/documentation/toaster-manual/figures/import-layer.png b/documentation/toaster-manual/figures/import-layer.png
new file mode 100644
index 0000000000..436ec7af4a
Binary files /dev/null and b/documentation/toaster-manual/figures/import-layer.png differ
diff --git a/documentation/toaster-manual/figures/new-project.png b/documentation/toaster-manual/figures/new-project.png
new file mode 100644
index 0000000000..dbc50b9918
Binary files /dev/null and b/documentation/toaster-manual/figures/new-project.png differ
diff --git a/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
index 3e05eb2828..2e465f432b 100644
--- a/documentation/toaster-manual/toaster-manual-setup-and-use.xml
+++ b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
@@ -115,451 +115,515 @@
To access the Django administration interface, you must
create a superuser by following these steps:
-
- If you used virtualenv, which is
- recommended, to set up the Toaster system dependencies,
- you need be sure the virtual environment is activated.
- To activate this environment, use the following:
-
- $ source venv/bin/activate
-
-
-
- From the directory containing the Toaster database,
- which by default is the
- Build Directory,
- invoke the createsuperuser command
- from manage.py:
-
- $ cd ~/poky/build
- $ ../bitbake/lib/toaster/manage.py createsuperuser
-
-
-
- Django prompts you for the username, which you need to
- provide.
-
-
- Django prompts you for an email address, which is
- optional.
-
-
- Django prompts you for a password, which you must provide.
-
-
- Django prompts you to re-enter your password for verification.
-
-
- After completing these steps, the following confirmation message
- appears:
-
- Superuser created successfully.
-
-
+
+ If you used virtualenv, which is
+ recommended, to set up the Toaster system dependencies,
+ you need be sure the virtual environment is activated.
+ To activate this environment, use the following:
+
+ $ source venv/bin/activate
+
+
+
+ From the directory containing the Toaster database,
+ which by default is the
+ Build Directory,
+ invoke the createsuperuser command
+ from manage.py:
+
+ $ cd ~/poky/build
+ $ ../bitbake/lib/toaster/manage.py createsuperuser
+
+
+
+ Django prompts you for the username, which you need to
+ provide.
+
+
+ Django prompts you for an email address, which is
+ optional.
+
+
+ Django prompts you for a password, which you must provide.
+
+
+ Django prompts you to re-enter your password for verification.
+
+
+ After completing these steps, the following confirmation message
+ appears:
+
+ Superuser created successfully.
+
+
-
- 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:
-
- http://127.0.0.1:8000/admin
-
- 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.
-
-
+
+ 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:
+
+ http://127.0.0.1:8000/admin
+
+ 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.
+
+
-
- Setting Up a Production Instance of Toaster
+
+ Setting Up a Production Instance of Toaster
-
- 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 cope with
- 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.
-
+
+ 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 cope with
+ 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.
+
-
- Requirements
+
+ Requirements
-
- Be sure you meet the following requirements:
-
- You must comply with all Apache,
- mod-wsgi, and Mysql requirements.
-
-
-
- Have all the build requirements as described in
- "Setting Up the Basic System Requirements"
- chapter.
-
-
- Have an Apache webserver.
-
-
- Have mod-wsgi for the Apache
- webserver.
-
-
- Use the Mysql database server.
-
-
- If you are using Ubuntu 14.04.3, run the following:
-
- $ sudo apt-get install apache2 libapache2-mod-wsgi mysql-server virtualenv libmysqlclient-dev
-
-
-
- If you are using Fedora 22 or a RedHat distribution, run
- the following:
-
- $ sudo dnf install httpd mod_wsgi python-virtualenv gcc mysql-devel
-
-
-
-
-
+
+ Be sure you meet the following requirements:
+
+ You must comply with all Apache,
+ mod-wsgi, and Mysql requirements.
+
+
+
+ Have all the build requirements as described in
+ "Setting Up the Basic System Requirements"
+ chapter.
+
+
+ Have an Apache webserver.
+
+
+ Have mod-wsgi for the Apache
+ webserver.
+
+
+ Use the Mysql database server.
+
+
+ If you are using Ubuntu 14.04.3, run the following:
+
+ $ sudo apt-get install apache2 libapache2-mod-wsgi mysql-server virtualenv libmysqlclient-dev
+
+
+
+ If you are using Fedora 22 or a RedHat distribution, run
+ the following:
+
+ $ sudo dnf install httpd mod_wsgi python-virtualenv gcc mysql-devel
+
+
+
+
+
-
- Installation
+
+ Installation
-
- Perform the following steps to install Toaster:
-
-
- Checkout a copy of poky
- into the web server directory.
- You will be using /var/www/toaster:
-
- $ mkdir -p /var/www/toaster
- $ cd /var/www/toaster/
- $ git clone git://git.yoctoproject.org/poky
- $ git checkout &DISTRO_NAME;
-
-
-
- Initialize a virtual environment and install Toaster
- dependencies.
- Using a virtual environment keeps the Python packages
- isolated from your system-provided packages:
-
- $ cd /var/www/toaster/
- $ virtualenv venv
- $ source ./venv/bin/activate
- $ pip install -r ./poky/bitbake/toaster-requirements.txt
- $ pip install mysql
- $ pip install MySQL-python
-
-
- Isolating these packages is not required but is
- recommended.
- Alternatively, you can use your operating system's
- package manager to install the packages.
-
-
-
- Configure Toaster by editing
- /var/www/toaster/poky/bitbake/lib/toaster/toastermain/settings.py
- as follows:
-
-
- Edit the DATABASE settings:
-
- DATABASES = {
- 'default': {
- 'ENGINE': 'django.db.backends.mysql',
- 'NAME': 'toaster_data',
- 'USER': 'toaster',
- 'PASSWORD': 'yourpasswordhere',
- 'HOST': 'localhost',
- 'PORT': '3306',
- }
- }
-
-
-
- Edit the SECRET_KEY:
-
- SECRET_KEY = 'your_secret_key'
-
-
-
- Edit the STATIC_ROOT:
-
- STATIC_ROOT = '/var/www/toaster/static_files/'
-
-
-
-
-
- Add the database and user to the mysql
- server defined earlier:
-
- $ 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
-
-
-
- Get Toaster to create the database schema,
- default data, and gather the statically-served files:
-
- $ cd /var/www/toaster/poky/
- $ ./bitbake/lib/toaster/manage.py syncdb
- $ ./bitbake/lib/toaster/manage.py migrate
- $ TOASTER_DIR=`pwd` TOASTER_CONF=./meta-yocto/conf/toasterconf.json ./bitbake/lib/toaster/manage.py checksettings
- $ ./bitbake/lib/toaster/manage.py collectstatic
-
-
+
+ Perform the following steps to install Toaster:
+
+
+ Checkout a copy of poky
+ into the web server directory.
+ You will be using /var/www/toaster:
+
+ $ mkdir -p /var/www/toaster
+ $ cd /var/www/toaster/
+ $ git clone git://git.yoctoproject.org/poky
+ $ git checkout &DISTRO_NAME;
+
+
+
+ Initialize a virtual environment and install Toaster
+ dependencies.
+ Using a virtual environment keeps the Python packages
+ isolated from your system-provided packages:
+
+ $ cd /var/www/toaster/
+ $ virtualenv venv
+ $ source ./venv/bin/activate
+ $ pip install -r ./poky/bitbake/toaster-requirements.txt
+ $ pip install mysql
+ $ pip install MySQL-python
+
+
+ Isolating these packages is not required but is
+ recommended.
+ Alternatively, you can use your operating system's
+ package manager to install the packages.
+
+
+
+ Configure Toaster by editing
+ /var/www/toaster/poky/bitbake/lib/toaster/toastermain/settings.py
+ as follows:
+
+
+ Edit the DATABASE settings:
+
+ DATABASES = {
+ 'default': {
+ 'ENGINE': 'django.db.backends.mysql',
+ 'NAME': 'toaster_data',
+ 'USER': 'toaster',
+ 'PASSWORD': 'yourpasswordhere',
+ 'HOST': 'localhost',
+ 'PORT': '3306',
+ }
+ }
+
+
+
+ Edit the SECRET_KEY:
+
+ SECRET_KEY = 'your_secret_key'
+
+
+
+ Edit the STATIC_ROOT:
+
+ STATIC_ROOT = '/var/www/toaster/static_files/'
+
+
+
+
+
+ Add the database and user to the mysql
+ server defined earlier:
+
+ $ 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
+
+
+
+ Get Toaster to create the database schema,
+ default data, and gather the statically-served files:
+
+ $ cd /var/www/toaster/poky/
+ $ ./bitbake/lib/toaster/manage.py syncdb
+ $ ./bitbake/lib/toaster/manage.py migrate
+ $ TOASTER_DIR=`pwd` TOASTER_CONF=./meta-yocto/conf/toasterconf.json ./bitbake/lib/toaster/manage.py checksettings
+ $ ./bitbake/lib/toaster/manage.py collectstatic
+
+
-
- For the above set of commands, after moving to the
- poky directory,
- the syncdb and migrate
- commands ensure the database
- schema has had changes propagated correctly (i.e.
- migrations).
-
+
+ For the above set of commands, after moving to the
+ poky directory,
+ the syncdb and migrate
+ commands ensure the database
+ schema has had changes propagated correctly (i.e.
+ migrations).
+
-
- The next line sets the Toaster root directory
- TOASTER_DIR and the location of
- the Toaster configuration file
- TOASTER_CONF, which is
- relative to the Toaster root directory
- TOASTER_DIR.
- For more information on the Toaster configuration file
- TOASTER_CONF, see the
- JSON Files
- section of this manual.
-
+
+ The next line sets the Toaster root directory
+ TOASTER_DIR and the location of
+ the Toaster configuration file
+ TOASTER_CONF, which is
+ relative to the Toaster root directory
+ TOASTER_DIR.
+ For more information on the Toaster configuration file
+ TOASTER_CONF, see the
+ JSON Files
+ section of this manual.
+
-
- This line also runs the checksettings
- command, which configures the location of the Toaster
- Build directory.
- The Toaster root directory TOASTER_DIR
- determines where the Toaster build directory
- is created on the file system.
- In the example above,
- TOASTER_DIR is set as follows:
-
- /var/www/toaster/poky
-
- This setting causes the Toaster build directory to be:
-
- /var/www/toaster/poky/build
-
-
+
+ This line also runs the checksettings
+ command, which configures the location of the Toaster
+ Build directory.
+ The Toaster root directory TOASTER_DIR
+ determines where the Toaster build directory
+ is created on the file system.
+ In the example above,
+ TOASTER_DIR is set as follows:
+
+ /var/www/toaster/poky
+
+ This setting causes the Toaster build directory to be:
+
+ /var/www/toaster/poky/build
+
+
-
- Finally, the collectstatic 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.
-
-
- 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:
-
- /etc/apache2/conf-available/toaster.conf
-
- If you are using Fedora or RedHat, put it here:
-
- /etc/httpd/conf.d/toaster.conf
-
- Following is a sample Apache configuration for Toaster
- you can follow:
-
- Alias /static /var/www/toaster/static_files
- <Directory /var/www/toaster/static_files>
- Order allow,deny
- Allow from all
- Require all granted
- </Directory>
+
+ Finally, the collectstatic 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.
+
+
+ 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:
+
+ /etc/apache2/conf-available/toaster.conf
+
+ If you are using Fedora or RedHat, put it here:
+
+ /etc/httpd/conf.d/toaster.conf
+
+ Following is a sample Apache configuration for Toaster
+ you can follow:
+
+ Alias /static /var/www/toaster/static_files
+ <Directory /var/www/toaster/static_files>
+ Order allow,deny
+ Allow from all
+ Require all granted
+ </Directory>
- WSGIDaemonProcess toaster_wsgi python-path=/var/www/toaster/poky/bitbake/lib/toaster:/var/www/toaster/venv/lib/python2.7/site-packages
+ WSGIDaemonProcess toaster_wsgi python-path=/var/www/toaster/poky/bitbake/lib/toaster:/var/www/toaster/venv/lib/python2.7/site-packages
- WSGIScriptAlias / "/var/www/toaster/poky/bitbake/lib/toaster/toastermain/wsgi.py"
- <Location />
- WSGIProcessGroup toastern_wsgi
- </Location>
-
- If you are using Ubuntu or Debian,
- you will need to enable the config and module for Apache:
-
- $ sudo a2enmod wsgi
- $ sudo a2enconf toaster
- $ chmod +x bitbake/lib/toaster/toastermain/wsgi.py
-
- Finally, restart Apache to make sure all new configuration
- is loaded.
- For Ubuntu and Debian use:
-
- $ sudo service apache2 restart
-
- For Fedora and RedHat use:
-
- $ sudo service httpd restart
-
-
-
- Install the build runner service.
- This service needs to be running in order to dispatch
- builds.
- Use this command:
-
- /var/www/toaster/poky/bitbake/lib/toaster/manage.py runbuilds
-
- Here is an example:
-
- #!/bin/sh
- # toaster run builds dispatcher
- cd /var/www/toaster/
- source ./venv/bin/activate
- ./bitbake/lib/toaster/manage.py runbuilds
-
-
-
- You can now open up a browser and start using Toaster.
-
-
-
+ WSGIScriptAlias / "/var/www/toaster/poky/bitbake/lib/toaster/toastermain/wsgi.py"
+ <Location />
+ WSGIProcessGroup toastern_wsgi
+ </Location>
+
+ If you are using Ubuntu or Debian,
+ you will need to enable the config and module for Apache:
+
+ $ sudo a2enmod wsgi
+ $ sudo a2enconf toaster
+ $ chmod +x bitbake/lib/toaster/toastermain/wsgi.py
+
+ Finally, restart Apache to make sure all new configuration
+ is loaded.
+ For Ubuntu and Debian use:
+
+ $ sudo service apache2 restart
+
+ For Fedora and RedHat use:
+
+ $ sudo service httpd restart
+
+
+
+ Install the build runner service.
+ This service needs to be running in order to dispatch
+ builds.
+ Use this command:
+
+ /var/www/toaster/poky/bitbake/lib/toaster/manage.py runbuilds
+
+ Here is an example:
+
+ #!/bin/sh
+ # toaster run builds dispatcher
+ cd /var/www/toaster/
+ source ./venv/bin/activate
+ ./bitbake/lib/toaster/manage.py runbuilds
+
+
+
+ You can now open up a browser and start using Toaster.
+
+
+
-
- Using the Toaster Web Interface
+
+ Using the Toaster Web Interface
-
- The Toaster web interface allows you to do the following:
-
-
- Browse published layers in the
- OpenEmbedded Metadata Index
- that are available for your selected version of the build
- system.
-
-
- Import your own layers for building.
-
-
- Add and remove layers from your configuration.
-
-
- Set configuration variables.
-
-
- Select a target or multiple targets to build.
-
-
- Start your builds.
-
-
- See what was built (recipes and packages) and what
- packages were installed into your final image.
-
-
- Browse the directory structure of your image.
-
-
- See the value of all variables in your build configuration,
- and which files set each value.
-
-
- Examine error, warning and trace messages to aid in
- debugging.
-
-
- See information about the BitBake tasks executed and
- reused during your build, including those that used
- shared state.
-
-
- See dependency relationships between recipes, packages
- and tasks.
-
-
- See performance information such as build time, task time,
- CPU usage, and disk I/O.
-
-
-
+
+ The Toaster web interface allows you to do the following:
+
+
+ Browse published layers in the
+ OpenEmbedded Metadata Index
+ that are available for your selected version of the build
+ system.
+
+
+ Import your own layers for building.
+
+
+ Add and remove layers from your configuration.
+
+
+ Set configuration variables.
+
+
+ Select a target or multiple targets to build.
+
+
+ Start your builds.
+
+
+ See what was built (recipes and packages) and what
+ packages were installed into your final image.
+
+
+ Browse the directory structure of your image.
+
+
+ See the value of all variables in your build configuration,
+ and which files set each value.
+
+
+ Examine error, warning and trace messages to aid in
+ debugging.
+
+
+ See information about the BitBake tasks executed and
+ reused during your build, including those that used
+ shared state.
+
+
+ See dependency relationships between recipes, packages
+ and tasks.
+
+
+ See performance information such as build time, task time,
+ CPU usage, and disk I/O.
+
+
+
-
- Toaster Web Interface Videos
+
+ Toaster Web Interface Videos
-
- Following are several videos that show how to use the Toaster GUI:
-
- Build Configuration:
- This
- video
- overviews and demonstrates build configuration for Toaster.
-
- Build Custom Layers:
- This
- video
- shows you how to build custom layers that are used with
- Toaster.
-
- Toaster Homepage and Table Controls:
- 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.
-
- Build Dashboard:
- This
- video
- shows you the build dashboard, a page providing an
- overview of the information available for a selected build.
-
- Image Information:
- This
- video
- walks through the information Toaster provides
- about images: packages installed and root file system.
-
- Configuration:
- This
- video
- provides Toaster build configuration information.
-
- Tasks:
- This
- video
- shows the information Toaster provides about the
- tasks run by the build system.
-
- Recipes and Packages Built:
- This
- video
- shows the information Toaster provides about recipes
- and packages built.
-
- Performance Data:
- This
- video
- shows the build performance data provided by
- Toaster.
-
-
-
-
+
+ Following are several videos that show how to use the Toaster GUI:
+
+ Build Configuration:
+ This
+ video
+ overviews and demonstrates build configuration for Toaster.
+
+ Build Custom Layers:
+ This
+ video
+ shows you how to build custom layers that are used with
+ Toaster.
+
+ Toaster Homepage and Table Controls:
+ 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.
+
+ Build Dashboard:
+ This
+ video
+ shows you the build dashboard, a page providing an
+ overview of the information available for a selected build.
+
+ Image Information:
+ This
+ video
+ walks through the information Toaster provides
+ about images: packages installed and root file system.
+
+ Configuration:
+ This
+ video
+ provides Toaster build configuration information.
+
+ Tasks:
+ This
+ video
+ shows the information Toaster provides about the
+ tasks run by the build system.
+
+ Recipes and Packages Built:
+ This
+ video
+ shows the information Toaster provides about recipes
+ and packages built.
+
+ Performance Data:
+ This
+ video
+ shows the build performance data provided by
+ Toaster.
+
+
+
+
-
- Building a Specific Recipe Given Multiple Versions
+
+ A Note on the Local Yocto Project Release
+
+
+ This note only applies if you have set up Toaster
+ for local development, as explained in
+
+ section 3.1.
+
+
+ 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.
+
+
+
+
+ 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.
+
+
+
+ If you select any of the other release options, Toaster
+ will fetch the tip of your selected release from the upstream
+ Yocto Project
+ repository every time you run a build. This 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
+ to happen. In that case, the Local Yocto Project
+ release might be the right choice.
+
+
+
+ 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:
+
+
+ openembedded-core
+
+
+ meta-poky
+
+
+ meta-yocto-bsp
+
+
+
+
+
+
+ If you want to build any other layers, you will need to
+ manually import them into your Toaster project, using the
+ Import layer page.
+
+
+
+
+
+
+ Building a Specific Recipe Given Multiple Versions
Occasionally, a layer might provide more than one version of