From 586992d24e3f0b8d0dfa194f7609fae0364ec390 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 13 Feb 2015 07:48:24 -0800 Subject: toaster-manual: 2nd draft for review. Fixes [YOCTO #6901] This is the 2nd review draft of the manual. (From yocto-docs rev: 9f541e4421e0e74e59e3b3da1896b6c1254daf08) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../toaster-manual/toaster-manual-intro.xml | 111 +++-- .../toaster-manual-setup-and-use.xml | 535 +++++++++++---------- .../toaster-manual/toaster-manual-start.xml | 18 +- 3 files changed, 374 insertions(+), 290 deletions(-) (limited to 'documentation/toaster-manual') 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: - - $ 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: - - $ bitbake core-image-minimal - - - + This section describes how to use Toaster in Analysis Mode + after setting Toaster up as a local instance or as a hosted + service. - - For information on how to use Toaster, see the - "Using the Toaster Interface" - section. - -
+
+ Setting Up Locally and Running in Analysis Mode -
- Setting Up a Production Instance + + 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: + + $ bitbake core-image-minimal + + + + - - 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. - + + For information on how to use Toaster, see the + "Using the Toaster Interface" + section. + +
- - 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. - +
+ Setting Up a Hosted Service and Running in Analysis Mode - - 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. - + + 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. + - - 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. + + 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. + - 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. + + 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. + - 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. + + 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. + - 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 @@
- -- cgit 1.2.3-korg