From 9d033d83cc8d31c9cf545231119f85a2cf9d0154 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 3 Feb 2015 11:09:28 -0800 Subject: [PATCH] toaster-manual: Added two chapter files. Fixes [YOCTO #6901] These are the second and third chapters of the Toaster Manual. (From yocto-docs rev: 6ff4e3dfff391efdbb0f36dc6800bf115abcfc92) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../toaster-manual-setup-and-use.xml | 326 ++++++++++++++++++ .../toaster-manual/toaster-manual-start.xml | 75 ++++ 2 files changed, 401 insertions(+) create mode 100644 documentation/toaster-manual/toaster-manual-setup-and-use.xml create mode 100644 documentation/toaster-manual/toaster-manual-start.xml diff --git a/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/documentation/toaster-manual/toaster-manual-setup-and-use.xml new file mode 100644 index 0000000000..ac9e9313ff --- /dev/null +++ b/documentation/toaster-manual/toaster-manual-setup-and-use.xml @@ -0,0 +1,326 @@ + %poky; ] > + + + +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. + + +
+ Setting Up a Local Instance + + + 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 + + + + + + + For information on how to use Toaster, see the + "Using the Toaster Interface" + section. + +
+ +
+ Setting Up a Production Instance + + + 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. + + + + 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. + + + + 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. + + + + 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. + + 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: + + $ 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: + + $ 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: + + 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: + + $ 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: + + $ bitbake -m + + + + + + + For information on how to use Toaster, see the + "Using the Toaster Interface" + section. + +
+ +
+ Setting Up a Hosted Managed Mode for Toaster + + + (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. + +
+ +
+ Using the Toaster Interface + + + The Toaster interface allows you to examine the following: + + + Outcome of the build, errors and warnings thrown + + + Packages included in an image + + + Image directory structure + + + Build configuration + + + Recipes and packages built + + + Full dependency chain for tasks, recipes and packages + + + Tasks run by the build system + + + Performance information such as time, CPU usage, and + disk I/O per task + + + For several useful videos that show how to effectively use the + 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.) + +
+ + + + diff --git a/documentation/toaster-manual/toaster-manual-start.xml b/documentation/toaster-manual/toaster-manual-start.xml new file mode 100644 index 0000000000..93f48c7b26 --- /dev/null +++ b/documentation/toaster-manual/toaster-manual-start.xml @@ -0,0 +1,75 @@ + %poky; ] > + + + +Preparing to Use Toaster + + + 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. + + +
+ 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 + "What You Need and How You Get It" + section in the Yocto Project Quick Start for information on how + to set up your system for the Yocto Project. + +
+ +
+ Establishing Toaster System Dependencies + + + Toaster requires extra Python dependencies that Bitbake + does not need in order to run. + In order to make it easy to run Toaster, a requirements file + located in the root directory of + Source Directory + bitbake/ + (e.g. poky/bitbake/toaster-requirements.txt). + The dependencies appear in a pip, + install-compatible format: + + Django==1.6 + South==0.8.4 + argparse==1.2.1 + wsgiref==0.1.2 + + Follow these steps to get set up: + + Create and activate a virtual environment: + + $ virtualenv venv + $ source venv/bin/activate + + + Use pip to install needed packages: + + $ pip install -r bitbake/toaster-requirements.txt + + + + Once you complete these steps, you execute in a lightweight + "virtual environment” with its own site directories that are + optionally isolated from system site directories. + The virtual environment has its own Python binary + (allowing creation of environments with various Python versions) + and can have its own independent set of installed Python packages + in its site directories. + +
+ + +