diff --git a/documentation/toaster-manual/toaster-manual-intro.xml b/documentation/toaster-manual/toaster-manual-intro.xml
index ad9e08b50d..9f4c38b2d4 100644
--- a/documentation/toaster-manual/toaster-manual-intro.xml
+++ b/documentation/toaster-manual/toaster-manual-intro.xml
@@ -39,7 +39,7 @@
You can use Toaster in Analysis Mode or Build Mode:
- Analysis Mode:
+ Analysis Mode:
In Analysis Mode, you can record builds and statistics.
In this Mode, you directly access the
bitbake command, which you then use to
@@ -82,7 +82,7 @@
- Build Mode:
+ Build Mode:
In Build Mode, Toaster handles the build configuration,
scheduling and execution.
In this mode, all your interaction with the build system
diff --git a/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
index 57a4343bc4..eb2de9b673 100644
--- a/documentation/toaster-manual/toaster-manual-setup-and-use.xml
+++ b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
@@ -6,9 +6,469 @@
Setting Up and Using Toaster
-
+
+ Starting Toaster for Local Development
+
+
+ Once you have set up the Yocto Project and installed the
+ Toaster system dependencies as described in
+ "Preparing to Use Toaster",
+ you are ready to start Toaster.
+
+
+
+ If you want to configure and start your builds using the
+ Toaster web interface
+ (i.e. "Build Mode"),
+ navigate to the root of your
+ Source Directory
+ (e.g. poky):
+
+ $ cd poky
+
+ Next, start Toaster:
+
+ $ bitbake/bin/toaster
+
+ Open your favourite browser and enter the following:
+
+ http://127.0.0.1:8000
+
+ If you would rather configure and start your builds
+ using the command line
+ (i.e. Analysis Mode),
+ you can get Toaster to "listen"
+ to your builds and collect information about them.
+ To do that, navigate to the root of your Source Directory:
+
+ $ cd poky
+
+ Once in that directory, source the build environment script:
+
+ $ source oe-init-build-env
+
+ Next, from the build directory (e.g.
+ poky/build), start Toaster using this
+ command:
+
+ $ source ../bitbake/bin/toaster
+
+ You can now run builds normally.
+
+
+
+ To see the build information provided by Toaster, open your
+ favorite browser and enter the following:
+
+ http://127.0.0.1:8000
+
+
+
+
+
+ Setting a Different Port
+
+
+ By default, Toaster starts on port 8000.
+ You can use the WEBPORT parameter to
+ set a different port.
+ For example, either of the following commands sets the
+ port to "8400":
+
+ $ bitbake/bin/toaster webport=8400
+
+ or
+
+ $ source ../bitbake/bin/toaster webport=8400
+
+
+
+
+
+ The Directory for Cloning Layers
+
+
+ If you are running Toaster in Build Mode, Toaster creates
+ a _toaster_clones directory inside
+ your Source Directory (i.e. poky).
+ For example, suppose you use this command to start Toaster:
+
+ poky/bitbake/bin/toaster
+
+ In this example, Toaster creates and uses the
+ poky/_toaster_clones
+ directory to clone any layers needed for your builds.
+
+
+
+ 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 TOASTER_DIR
+ environment variable, which takes precedence over your current
+ working directory.
+ Setting this environment variable causes Toaster to create and use
+ $TOASTER_DIR./_toaster_clones.
+
+
+
+
+ The Build Directory
+
+
+ If you are running Toaster in Build Mode, Toaster creates a
+ build directory within your Source Directory (e.g.
+ poky).
+ For example, suppose you use this command to start Toaster:
+
+ poky/bitbake/bin/toaster
+
+ In this example, Toaster creates and uses the
+ poky/_toaster_clones
+ directory to execute the builds.
+
+
+
+ Alternatively, if you would like all of your Toaster related files
+ and directories to be in a particular location, you can set
+ the TOASTER_DIR environment variable,
+ which takes precedence over your current working directory.
+ Setting this environment variable causes Toaster to use
+ $TOASTER_DIR./build as the build directory.
+
+
+
+
+ Creating a Django Superuser
+
+
+ Toaster is built on the Django framework.
+ Django provides an administration interface you can use
+ to edit Toaster configuration parameters.
+
+
+
+ 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 root of your checkout directory, invoke the
+ following command from manage.py:
+
+ $ ./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.
+
+
+
+
+ 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 in
+ Build Mode
+ where builds and projects are run,
+ viewed, and defined through the Toaster web interface.
+
+
+
+ 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
+
+
+
+
+
+
+
+ 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/'
+
+
+
+ Enable Build Mode by adding the following
+ line to settings.py:
+
+ BUILD_MODE=True
+
+
+
+
+
+ Add the database and user to the mysql
+ server defined earlier:
+
+ $ mysql -u root -p
+ mysql> CREATE DATABASE toaster;
+ 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 --migrate
+ $ ./bitbake/lib/toaster/manage.py loadconf ./meta-yocto/conf/toasterconf.json
+ $ ./bitbake/lib/toaster/manage.py lsupdates
+ $ ./bitbake/lib/toaster/manage.py collectstatic
+
+
+
+
+ For the above set of commands, after moving to the
+ poky directory,
+ the syncdb command with the
+ migrate option makes sure the database
+ schema has had changes propagated correctly (i.e.
+ migrations).
+ See the
+ syncdb
+ command for more information.
+
+
+
+ The
+ loadconf
+ command loads the
+ ./meta-yocto/conf/toasterconf.json
+ JSON file.
+
+
+
+ The lsupdates command fetches the
+ initial recipes and layers data from the layer index.
+
+
+
+ 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.
+ For more information on this Django command, see
+ .
+
+
+ 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
+
+ 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
+
+ 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
@@ -875,6 +1336,12 @@
Following are several videos that show how to use the Toaster GUI:
+ Build Custom Layers:
+ This
+ video
+ shows you how to build custom layers that are used with
+ Toaster.
+ Build Configuration:
This
video
diff --git a/documentation/toaster-manual/toaster-manual-start.xml b/documentation/toaster-manual/toaster-manual-start.xml
index 32be3a8473..daefa79090 100644
--- a/documentation/toaster-manual/toaster-manual-start.xml
+++ b/documentation/toaster-manual/toaster-manual-start.xml
@@ -15,12 +15,13 @@
Setting Up the Basic System Requirements
- You first need to be sure your build system is set up to run
- the Yocto Project.
- See the
- "Setting Up to Use the Yocto Project"
- section in the Yocto Project Quick Start for information on how
- to set up your system for the Yocto Project.
+ Before you can use Toaster, you need to first set up your
+ build system to run the Yocto Project.
+ To do this, follow the instructions in the
+ "The Build Host Packages"
+ and
+ "Yocto Project Release"
+ sections in the Yocto Project Quick Start.