diff --git a/documentation/toaster-manual/toaster-manual-intro.xml b/documentation/toaster-manual/toaster-manual-intro.xml
index 36c3b6bdc0..378f33420c 100644
--- a/documentation/toaster-manual/toaster-manual-intro.xml
+++ b/documentation/toaster-manual/toaster-manual-intro.xml
@@ -6,10 +6,13 @@
Introduction
- Toaster is an Application Programming Interface (API) and
- web-based interface to the OpenEmbedded build system, which uses
+ Toaster is web interface to the OpenEmbedded build system, which uses
BitBake.
- Both interfaces are based on a Representational State Transfer
+ The interface allows you to access a datastore that retains build
+ information and report out on the information.
+
+
You can use Toaster in several different modes:
- Interactive Mode:
+ Analysis Mode:
In this mode, you can record builds and statistics.
- In Interactive Mode, you have direct access to the
+ In Analysis Mode, you have direct access to the
bitbake command, which you use to build
- images.
+ images.
+ Analysis Mode requires you to have first started
+ Toaster and then to initiate your build using the
+ bitbake command from the shell.
+ Toaster must be started before the build or it will not
+ collect build data.
- Managed Mode:
+ Build Mode:
In this mode, Toaster handles the build configuration GUI
- (through Project pages) and build scheduling and execution.
- Additionally, in addition to these features, builds are
- triggered through the web interface.
+ (through project pages) and build scheduling and execution.
+ In this mode, all your interaction with the build system
+ happens through the web interface.
You do not have direct access to the
bitbake command.
-
- Managed Mode also works two separate ways: Local
- Managed Mode and Remote Managed Mode.
- Local Managed Mode is the out-of-box mode available once
- you checkout poky and allows you to perform builds on your
- local machine.
- Remote Managed Mode, also known as Hosted Toaster, is a
- production setup best for organizations supporting multiple
- users and for organizations using customized Toaster
- installations.
+ Using this mode, you configure and start your builds
+ with Toaster's GUI.
+ Each configuration is a project, which requires version and
+ build system selection.
+ As shipped, Toaster supports the Yocto Project releases
+ 1.8 and beyond.
+ Aside from these supported releases, you can also select
+ the "Local Yocto Project", which allows you to use your
+ local clone of the Yocto Project
+ Source Directory
+ (e.g. poky).
+ Build Mode also works two separate ways: locally and
+ remotely.
+ While you can use Build Mode locally, it is best to use
+ Toaster's Build Mode through a hosted service where it can
+ shared by multiple user.
- Using the interfaces you can do the following:
+ Using Toaster, you can do the following:
+ REVIEWER NOTE
+ Belen suggested we split this list out into things that
+ Analysis Mode and Build Mode can do.
+ Also, we can structure the lists so the Build Mode list
+ leverages off what is listed for Analysis Mode.
+ I do not know the information for the complete lists.
+ Someone needs to help me out here.
+ For now, I am leaving the list as follows and will need some
+ information.
+
- See information about the tasks executed
- and reused during the build.
- See what is built (recipes and
+
+ See information about the tasks executed
+ and reused during the build.
+
+
+ See what is built (recipes and
packages) and what packages were installed into the final
- image.
- See performance-related information such
- as build time, CPU usage, and disk I/O.
- Examine error, warning and trace messages
- to aid in debugging.
+ image.
+
+
+ See performance-related information such
+ as build time, CPU usage, and disk I/O.
+
+
+ Examine error, warning and trace messages
+ to aid in debugging.
+
- This release of Toaster provides you with information
- about a BitBake run.
- The tool does not allow you to configure and launch a build.
- However, future development includes plans to integrate the
- configuration and build launching capabilities of
+ This release of Toaster does allow you to configure and initiate
+ builds.
+ However, you cannot use Toaster to customize image recipes, which
+ still must either be done by hand or through
Hob.
+ As Toaster matures, it eventually will equal and surpass Hob
+ functionality, at which time Hob will be deprecated.
- For more information on using Hob to build an image,
+ For more information on Hob,
see the
"Image Development Using Hob"
section in the Yocto Project Development Manual.
@@ -85,6 +119,9 @@
The remainder of this manual describes what you need to have in
place to use Toaster, how to start it, use it, and stop it.
+
+
+
+
diff --git a/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
index ac9e9313ff..f56d67ed37 100644
--- a/documentation/toaster-manual/toaster-manual-setup-and-use.xml
+++ b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
@@ -7,273 +7,317 @@
Setting Up and Using Toaster
- You can set up local and production instances of Toaster.
- This chapter describes how to set up both these types of instances.
+ You can set up Toaster as a local instance or as a hosted service.
+ Furthermore, you can use Toaster in Analysis Mode or Build Mode
+ from both set ups.
-
- Setting Up a Local Instance
+
+ Using Toaster in Analysis Mode
- Follow these steps to set up and run a local instance of Toaster:
-
- Prepare your build system:
- Be sure your system has the Toaster requirements
- by following the steps in the
- "Establishing Toaster System Dependencies"
- section.
-
- Get Set Up to Use the Yocto Project:
- Get the requirements set up so that you can use the
- Yocto Project to build images.
- See the
- "What You Need and How You Get It"
- section in the Yocto Project Quick Start for information.
-
- Be sure Ports are free:
- Make sure that port 8000 and 8200 are free.
- In other words, make sure the ports do not have servers
- on them.
-
- Source your Build Environment Setup Script:
- From your
- Build Directory
- (e.g. poky/build), source the build
- environment setup script (i.e.
- &OE_INIT_FILE;
- or
- oe-init-build-env-memres).
-
- Start Toaster:
- From the
- Build Directory,
- start Toaster:
-
+ This section describes how to use Toaster in Analysis Mode
+ after setting Toaster up as a local instance or as a hosted
+ service.
+
+
+
+ Setting Up Locally and Running in Analysis Mode
+
+
+ Follow these steps to set up a local instance of Toaster and
+ then run in Analysis Mode:
+
+ Prepare your Build System:
+ Be sure your system has the Toaster requirements
+ by following the steps in the
+ "Establishing Toaster System Dependencies"
+ section.
+
+ Get Set Up to Use the Yocto Project:
+ Get the requirements set up so that you can use the
+ Yocto Project to build images.
+ See the
+ "What You Need and How You Get It"
+ section in the Yocto Project Quick Start for information.
+
+ Be Sure Ports are Free:
+ Make sure that port 8000 and 8200 are free.
+ In other words, make sure the ports do not have servers
+ on them.
+
+ Source your Build Environment Setup Script:
+ From your
+ Build Directory
+ (e.g. poky/build), source the build
+ environment setup script (i.e.
+ &OE_INIT_FILE;
+ or
+ oe-init-build-env-memres).
+
+ Start Toaster:
+ From the
+ Build Directory,
+ start Toaster:
+
$ source toaster start
-
-
- Start Your Build using BitBake:
- Use the bitbake command to start your
- build.
- Here is an example that builds the
- core-image-minimal image:
-
+
+
+ Start Your Build Using BitBake:
+ Use the bitbake command to start your
+ build.
+ Here is an example that builds the
+ core-image-minimal image:
+
$ bitbake core-image-minimal
-
-
-
-
+
+
+
+
-
- For information on how to use Toaster, see the
- "Using the Toaster Interface"
- section.
-
-
+
+ For information on how to use Toaster, see the
+ "Using the Toaster Interface"
+ section.
+
+
-
- Setting Up a Production Instance
+
+ Setting Up a Hosted Service and Running in Analysis Mode
-
- A production instance of Toaster resides on a server and allows
- multiple users to take advantage of Toaster.
- In a production environment, you might want to have multiple
- instances of Toaster running on various remote build machines.
- You can create this situation by basically modifying how Toaster
- starts.
-
+
+ A hosted service resides on a server and allows
+ multiple users to take advantage of Toaster.
+ In a production environment, you might want to have multiple
+ local instances of Toaster, which run on various remote
+ build machines, and have those local instances access and use
+ a single hosted Toaster service.
+
-
- Starting Toaster with the toaster command
- (i.e. the script), causes three things to start:
-
-
- The BitBake server.
-
-
- the Toaster User Interface, which connects to the
- BitBake server on one side and to the SQL
- database on the other side.
-
-
- The web server, which reads the database and displays the
- web user interface.
-
-
- Rather than starting Toaster with the script, you can set up
- and start multiple instances of Toaster by manually starting
- as many or few of these three components across your environment.
- This is possible because it is not required that Toaster starts
- all three of its separate components in order to run.
- Minimally, an instance of Toaster requires just one of the
- components.
-
+
+ Starting Toaster with the toaster command
+ (i.e. the script), causes three things to start:
+
+
+ The BitBake server.
+
+
+ The Toaster User Interface, which connects to the
+ BitBake server on one side and to the SQL
+ database on the other side.
+
+
+ The web server, which reads the database and displays
+ the web user interface.
+
+
+ Rather than starting Toaster with the script, you can set up
+ and start multiple instances of Toaster by manually starting
+ as many or few of these three components across your
+ environment.
+ This is possible because it is not required that Toaster starts
+ all three of its separate components in order to run.
+ Minimally, a local instance of Toaster requires just one of the
+ components.
+
-
- The concepts for setting up multiple instances of Toaster revolve
- around maintaining a common SQL database and Web server that
- show data from that common database as well as setting up
- separate instances of BitBake servers and Toaster user interfaces
- for each separate BitBake build directory.
- The common SQL database and the Web server show data from all the
- various BitBake builds.
- Setting the SQL database outside of any
- Build Directory
- maintains a separation layer between the various builds.
- The database is persistent because the logging database is set
- up external to the database server (e.g. MySQL).
- It is not even necessary to run the BitBake servers, the SQL
- server, and the Web server on the same machine.
- Each component can be run on its own machine.
-
+
+ The concepts for setting up multiple local instances of
+ Toaster that share a single hosted service revolve
+ around maintaining a common SQL database and Web server that
+ shows data from that common database as well as setting up
+ separate local instances of BitBake servers and Toaster user
+ interfaces for each of those separate BitBake build
+ directories.
+
-
- Follow these steps to set up and run a production instance of
- Toaster:
-
- Prepare your build system:
- Be sure your system has the Toaster requirements
- by following the steps in the
- "Establishing Toaster System Dependencies"
- section.
-
- Get Set Up to Use the Yocto Project:
- Get the requirements set up so that you can use the
- Yocto Project to build images.
- See the
- "What You Need and How You Get It"
- section in the Yocto Project Quick Start for information.
-
- Be sure Ports are free:
- Make sure that port 8000 and 8200 are free.
- In other words, make sure the ports do not have servers
- on them.
-
- Set up the SQL Logging Server and the Web Server:
- You can use any SQL server out of the box (e.g.
- mysgl-server for an Ubuntu build
- system).
-
- If you are concerned about performance, you might want
- to hand-tune the server.
-
- You must set up proper username and password access for
- the server for everyone that will be using Toaster.
- You need administration rights for the
- mysql root account, which is not the
- same thing as root access on the machine.
+
+ The common SQL database and the Web server show data from
+ all the various BitBake builds.
+ Setting the SQL database outside of any
+ Build Directory
+ maintains a separation layer between the various local builds
+ and the common database.
+ The database is persistent because the logging database is set
+ up external to the BitBake database server (e.g. MySQL).
+ It is not even necessary to run the BitBake servers, the SQL
+ server, and the Web server on the same machine.
+ Each component can be run on its own machine.
+
- Clone a separate, local Git repository of the
- Toaster master branch to use for running the Web server:
-
- $ git clone (NEED THE GIT REPO URL HERE)
-
- You do not perform builds on this tree.
- You need to create this local repository away from any
- build areas.
-
- In the separately cloned tree for the Web server,
- edit the
- bitbake/lib/toaster/toastermain/settings.py
- file so that the DATABASES value
- points to the previously created database server.
- Use the username and password established earlier.
-
- Run the database sync scripts to create the needed
- tables as follows:
-
+
+ Follow these steps to set up and run a hosted service and run
+ Toaster in Analysis Mode:
+
+ Prepare your Build System:
+ Be sure your system has the Toaster requirements
+ by following the steps in the
+ "Establishing Toaster System Dependencies"
+ section.
+
+ Get Set Up to Use the Yocto Project:
+ Get the requirements set up so that you can use the
+ Yocto Project to build images.
+ See the
+ "What You Need and How You Get It"
+ section in the Yocto Project Quick Start for information.
+
+ Be Sure Ports are Free:
+ Make sure that port 8000 and 8200 are free.
+ In other words, make sure the ports do not have servers
+ on them.
+
+ Set up the SQL Logging Server and the Web Server:
+ You can use any SQL server out of the box (e.g.
+ mysgl-server for an Ubuntu build
+ system).
+
+ If you are concerned about performance, you might
+ want to hand-tune the server.
+
+ You must set up proper username and password access on
+ the shared server for everyone that will be using
+ Toaster.
+ You need administration rights for the
+ mysql root account, which is not
+ the same thing as root access on the machine.
+ Clone a separate, local Git repository of the
+ Toaster master branch to use for running the Web
+ server.
+ The Git repository for Toaster is part of the
+ Yocto Project
+ Source Directory.
+ Consequently, you just need to set up a separate
+ local clone of the Yocto Project Source Directory
+ (e.g. poky):
+
+ $ git clone git://git.yoctoproject.org/poky
+
+ You do not perform builds on this tree.
+ You need to create this local repository away from any
+ build areas.
+ In the separately cloned tree for the Web server,
+ edit the
+ bitbake/lib/toaster/toastermain/settings.py
+ file so that the DATABASES value
+ points to the previously created database server.
+ Use the username and password established
+ earlier.
+ Run the database sync scripts to create the
+ needed tables as follows:
+
$ python bitbake/lib/toaster/manage.py syncdb
$ python bitbake/lib/toaster/manage.py migrate orm
-
- You can start the web server in the foreground or the
- background using these commands, respectively:
-
+
+ You can start the Web server in the foreground or the
+ background using these commands, respectively:
+
$ python bitbake/lib/toaster/manage.py runserver
$ nohup python bitbake/lib/toaster/manage.py runserver 2>toaster_web.log >toaster_web.log &
-
-
- Enable Build Logging to the Common SQL Server for Each Build Directory you are Using
- For each build system that will be using Toaster and the
- SQL server, you need to edit the
- bitbake/lib/toaster/toastermain/settings.py
- to alter the DATABASES value to point
- to the common SQL logging server.
- (I DON'T SEE HOW TO DO THIS FROM THE WIKI - I NEED MORE
- CLARIFICATION).
-
- In the Build Directory, create the required
- conf/toaster.conf file as described in
- BitBake Extra Options.
- Briefly, for each Build Directory, you need to inherit the
- toaster
- class by setting the following in your
- local.conf configuration file:
-
+
+
+ Enable Build Logging to the Common SQL Server for Each Build Directory you are Using:
+ For each build system that will be using Toaster and
+ the shared SQL server, you need to edit the
+ bitbake/lib/toaster/toastermain/settings.py
+ file to alter the DATABASES value
+ so that it points to the common SQL logging server.
+ REVIEWER NOTE
+ I don't see how to do this from the Wiki.
+ I need more clarification.
+
+ In the Build Directory, create the required
+ conf/toaster.conf file as
+ described in
+ BitBake Extra Options.
+ Briefly, for each Build Directory, you need to inherit
+ the
+ toaster
+ class by setting the following in your
+ local.conf configuration file:
+
INHERIT += "toaster"
INHERIT += "buildhistory"
BUILDHISTORY_COMMIT = "1"
-
- Start the BitBake server using the following command:
-
- $ bitbake --postread conf/toaster.conf --server-only -t xmlrpc -B localhost:0 && export BBSERVER=localhost:-1
-
- Start the logging user interface using the following
- command:
-
- $ nohup bitbake --observe-only -u toasterui >toaster_ui.log &
-
-
- No hard-coded ports are used as there is enough code
- to run autodiscovery
- for ports to prevent collisions.
-
-
- Source your Build Environment Setup Script:
- From your
- Build Directory
- on each of the build systems,
- (e.g. poky/build), source the build
- environment setup script (i.e.
- &OE_INIT_FILE;
- or
- oe-init-build-env-memres).
-
- Start Builds Using BitBake:
- Use the bitbake command to start a
- build on a build system.
- Here is an example that builds the
- core-image-minimal image:
-
+
+ Start the BitBake server using the following command:
+
+ $ bitbake ‐‐postread conf/toaster.conf ‐‐server-only -t xmlrpc -B localhost:0 && export BBSERVER=localhost:-1
+
+ Start the logging user interface using the following
+ command:
+
+ $ nohup bitbake ‐‐observe-only -u toasterui >toaster_ui.log &
+
+
+ No hard-coded ports are used as there is enough code
+ to run autodiscovery
+ for ports to prevent collisions.
+
+
+ Source your Build Environment Setup Script:
+ From your
+ Build Directory
+ on each of the build systems,
+ (e.g. poky/build), source the
+ build environment setup script (i.e.
+ &OE_INIT_FILE;
+ or
+ oe-init-build-env-memres).
+
+ Start Builds Using BitBake:
+ Use the bitbake command to start a
+ build on a build system.
+ Here is an example that builds the
+ core-image-minimal image:
+
$ bitbake core-image-minimal
-
- When you are finished with a build in a given
- Build Directory, be sure to kill
- the BitBake server for that build area:
-
+
+ When you are finished with a build in a given
+ Build Directory, be sure to kill
+ the BitBake server for that build area:
+
$ bitbake -m
-
-
-
-
+
+
+
+
-
- For information on how to use Toaster, see the
- "Using the Toaster Interface"
- section.
-
+
+ For information on how to use Toaster, see the
+ "Using the Toaster Interface"
+ section.
+
+
-
- Setting Up a Hosted Managed Mode for Toaster
+
+ Using Toaster in Build Mode
- (RIGHT NOW, THE
- WIKI PAGE
- HAS SOME INFORMATION ON THIS.
- I DON'T GET IT THOUGH.
- I NEED SOME MORE INFORMATION IN ORDER TO UNDERSTAND THIS AND
- CREATE A SECTION.
+ This section describes how to use Toaster in Build Mode
+ after setting Toaster up as a local instance or as a hosted
+ service.
+
+
+ Setting Up Locally and Running in Build Mode
+
+ REVIEWER NOTE
+ I need the information on how to do this.
+
+
+
+
+ Setting Up a Hosted Service and Running in Build Mode
+
+ REVIEWER NOTE
+ Right now, the
+ WIKI PAGE
+ has some information on this but I don't understand it.
+ I need more information.
+
+
@@ -312,15 +356,12 @@
Toaster interface, see the
Toaster Documentation
on the Yocto Project website.
- (SO WE NEED TO DECIDE IF THESE VIDS ARE GOING TO ROLL OVER INTO
- 1.8 AND REMAIN ON A "TOASTER MANUAL" PAGE AS THEY DO IN 1.7.
- OR, IF WE ARE GOING TO GET THE LINKS TO THE VIDS HERE IN THIS
- MANUAL.)
+ REVIEWER NOTE
+ We have agreed to get rid of the manual page on the website,
+ contains the links to the GUI videos.
+ We have agreed to host the videos on Vimeo and to embed the
+ videos in this new Toaster manual.
+
-
-
-
diff --git a/documentation/toaster-manual/toaster-manual-start.xml b/documentation/toaster-manual/toaster-manual-start.xml
index 93f48c7b26..b884036035 100644
--- a/documentation/toaster-manual/toaster-manual-start.xml
+++ b/documentation/toaster-manual/toaster-manual-start.xml
@@ -9,8 +9,8 @@
This chapter describes how you need to prepare your system in order to
use Toaster.
- Toaster requires some packages that you must have installed before trying
- to run Toaster.
+ Toaster requires some packages that you must have installed before
+ trying to run Toaster.
@@ -47,6 +47,17 @@
Follow these steps to get set up:
+ Install virtualenv:
+ virtualenv is a tool to create
+ isolated Python environments by creating folders that
+ contain all the necessary executables to use the packages
+ that Python projects need.
+ You can use pip to install
+ virtualenv:
+
+ $ pip install virtualenv
+
+ Create and activate a virtual environment:
$ virtualenv venv
@@ -70,6 +81,3 @@
-