summaryrefslogtreecommitdiffstats
path: root/documentation/toaster-manual
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2015-02-03 11:09:28 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2015-02-17 15:16:58 +0000
commit9d033d83cc8d31c9cf545231119f85a2cf9d0154 (patch)
tree96c5e6eefbd441ad1caf7b77bb7aa8eae1429f87 /documentation/toaster-manual
parente2f004faa3bf4bca0f12e86bc8b57d964a8ca818 (diff)
downloadpoky-9d033d83cc8d31c9cf545231119f85a2cf9d0154.tar.gz
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 <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/toaster-manual')
-rw-r--r--documentation/toaster-manual/toaster-manual-setup-and-use.xml326
-rw-r--r--documentation/toaster-manual/toaster-manual-start.xml75
2 files changed, 401 insertions, 0 deletions
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 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='toaster-manual-setup-and-use'>
6
7<title>Setting Up and Using Toaster</title>
8
9 <para>
10 You can set up local and production instances of Toaster.
11 This chapter describes how to set up both these types of instances.
12 </para>
13
14 <section id='toaster-setting-up-a-local-instance'>
15 <title>Setting Up a Local Instance</title>
16
17 <para>
18 Follow these steps to set up and run a local instance of Toaster:
19 <orderedlist>
20 <listitem><para><emphasis>Prepare your build system:</emphasis>
21 Be sure your system has the Toaster requirements
22 by following the steps in the
23 "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>"
24 section.
25 </para></listitem>
26 <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis>
27 Get the requirements set up so that you can use the
28 Yocto Project to build images.
29 See the
30 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>"
31 section in the Yocto Project Quick Start for information.
32 </para></listitem>
33 <listitem><para><emphasis>Be sure Ports are free:</emphasis>
34 Make sure that port 8000 and 8200 are free.
35 In other words, make sure the ports do not have servers
36 on them.
37 </para></listitem>
38 <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis>
39 From your
40 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
41 (e.g. <filename>poky/build</filename>), source the build
42 environment setup script (i.e.
43 <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink>
44 or
45 <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>).
46 </para></listitem>
47 <listitem><para><emphasis>Start Toaster:</emphasis>
48 From the
49 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
50 start Toaster:
51 <literallayout class='monospaced'>
52 $ source toaster start
53 </literallayout>
54 </para></listitem>
55 <listitem><para><emphasis>Start Your Build using BitBake:</emphasis>
56 Use the <filename>bitbake</filename> command to start your
57 build.
58 Here is an example that builds the
59 <filename>core-image-minimal</filename> image:
60 <literallayout class='monospaced'>
61 $ bitbake core-image-minimal
62 </literallayout>
63 </para></listitem>
64 </orderedlist>
65 </para>
66
67 <para>
68 For information on how to use Toaster, see the
69 "<link linkend='using-the-toaster-interface'>Using the Toaster Interface</link>"
70 section.
71 </para>
72 </section>
73
74 <section id='toaster-setting-up-a-production-instance'>
75 <title>Setting Up a Production Instance</title>
76
77 <para>
78 A production instance of Toaster resides on a server and allows
79 multiple users to take advantage of Toaster.
80 In a production environment, you might want to have multiple
81 instances of Toaster running on various remote build machines.
82 You can create this situation by basically modifying how Toaster
83 starts.
84 </para>
85
86 <para>
87 Starting Toaster with the <filename>toaster</filename> command
88 (i.e. the script), causes three things to start:
89 <itemizedlist>
90 <listitem><para>
91 The BitBake server.
92 </para></listitem>
93 <listitem><para>
94 the Toaster User Interface, which connects to the
95 BitBake server on one side and to the SQL
96 database on the other side.
97 </para></listitem>
98 <listitem><para>
99 The web server, which reads the database and displays the
100 web user interface.
101 </para></listitem>
102 </itemizedlist>
103 Rather than starting Toaster with the script, you can set up
104 and start multiple instances of Toaster by manually starting
105 as many or few of these three components across your environment.
106 This is possible because it is not required that Toaster starts
107 all three of its separate components in order to run.
108 Minimally, an instance of Toaster requires just one of the
109 components.
110 </para>
111
112 <para>
113 The concepts for setting up multiple instances of Toaster revolve
114 around maintaining a common SQL database and Web server that
115 show data from that common database as well as setting up
116 separate instances of BitBake servers and Toaster user interfaces
117 for each separate BitBake build directory.
118 The common SQL database and the Web server show data from all the
119 various BitBake builds.
120 Setting the SQL database outside of any
121 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
122 maintains a separation layer between the various builds.
123 The database is persistent because the logging database is set
124 up external to the database server (e.g. MySQL).
125 It is not even necessary to run the BitBake servers, the SQL
126 server, and the Web server on the same machine.
127 Each component can be run on its own machine.
128 </para>
129
130 <para>
131 Follow these steps to set up and run a production instance of
132 Toaster:
133 <orderedlist>
134 <listitem><para><emphasis>Prepare your build system:</emphasis>
135 Be sure your system has the Toaster requirements
136 by following the steps in the
137 "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>"
138 section.
139 </para></listitem>
140 <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis>
141 Get the requirements set up so that you can use the
142 Yocto Project to build images.
143 See the
144 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>"
145 section in the Yocto Project Quick Start for information.
146 </para></listitem>
147 <listitem><para><emphasis>Be sure Ports are free:</emphasis>
148 Make sure that port 8000 and 8200 are free.
149 In other words, make sure the ports do not have servers
150 on them.
151 </para></listitem>
152 <listitem><para><emphasis>Set up the SQL Logging Server and the Web Server:</emphasis>
153 You can use any SQL server out of the box (e.g.
154 <filename>mysgl-server</filename> for an Ubuntu build
155 system).
156 <note>
157 If you are concerned about performance, you might want
158 to hand-tune the server.
159 </note>
160 You must set up proper username and password access for
161 the server for everyone that will be using Toaster.
162 You need administration rights for the
163 <filename>mysql</filename> root account, which is not the
164 same thing as root access on the machine.</para>
165
166 <para>Clone a separate, local Git repository of the
167 Toaster master branch to use for running the Web server:
168 <literallayout class='monospaced'>
169 $ git clone (NEED THE GIT REPO URL HERE)
170 </literallayout>
171 You do not perform builds on this tree.
172 You need to create this local repository away from any
173 build areas.</para>
174
175 <para>In the separately cloned tree for the Web server,
176 edit the
177 <filename>bitbake/lib/toaster/toastermain/settings.py</filename>
178 file so that the <filename>DATABASES</filename> value
179 points to the previously created database server.
180 Use the username and password established earlier.</para>
181
182 <para>Run the database sync scripts to create the needed
183 tables as follows:
184 <literallayout class='monospaced'>
185 $ python bitbake/lib/toaster/manage.py syncdb
186 $ python bitbake/lib/toaster/manage.py migrate orm
187 </literallayout>
188 You can start the web server in the foreground or the
189 background using these commands, respectively:
190 <literallayout class='monospaced'>
191 $ python bitbake/lib/toaster/manage.py runserver
192 $ nohup python bitbake/lib/toaster/manage.py runserver 2>toaster_web.log >toaster_web.log &amp;
193 </literallayout>
194 </para></listitem>
195 <listitem><para><emphasis>Enable Build Logging to the Common SQL Server for Each Build Directory you are Using</emphasis>
196 For each build system that will be using Toaster and the
197 SQL server, you need to edit the
198 <filename>bitbake/lib/toaster/toastermain/settings.py</filename>
199 to alter the <filename>DATABASES</filename> value to point
200 to the common SQL logging server.
201 (I DON'T SEE HOW TO DO THIS FROM THE WIKI - I NEED MORE
202 CLARIFICATION).</para>
203
204 <para>In the Build Directory, create the required
205 <filename>conf/toaster.conf</filename> file as described in
206 <ulink url='https://wiki.yoctoproject.org/wiki/Setting_up_a_local_instance_of_Toaster'>BitBake Extra Options</ulink>.
207 Briefly, for each Build Directory, you need to inherit the
208 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-toaster'>toaster</ulink>
209 class by setting the following in your
210 <filename>local.conf</filename> configuration file:
211 <literallayout class='monospaced'>
212 INHERIT += "toaster"
213 INHERIT += "buildhistory"
214 BUILDHISTORY_COMMIT = "1"
215 </literallayout>
216 Start the BitBake server using the following command:
217 <literallayout class='monospaced'>
218 $ bitbake --postread conf/toaster.conf --server-only -t xmlrpc -B localhost:0 &amp;&amp; export BBSERVER=localhost:-1
219 </literallayout>
220 Start the logging user interface using the following
221 command:
222 <literallayout class='monospaced'>
223 $ nohup bitbake --observe-only -u toasterui >toaster_ui.log &amp;
224 </literallayout>
225 <note>
226 No hard-coded ports are used as there is enough code
227 to run <filename>autodiscovery</filename>
228 for ports to prevent collisions.
229 </note>
230 </para></listitem>
231 <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis>
232 From your
233 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
234 on each of the build systems,
235 (e.g. <filename>poky/build</filename>), source the build
236 environment setup script (i.e.
237 <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink>
238 or
239 <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>).
240 </para></listitem>
241 <listitem><para><emphasis>Start Builds Using BitBake:</emphasis>
242 Use the <filename>bitbake</filename> command to start a
243 build on a build system.
244 Here is an example that builds the
245 <filename>core-image-minimal</filename> image:
246 <literallayout class='monospaced'>
247 $ bitbake core-image-minimal
248 </literallayout>
249 When you are finished with a build in a given
250 Build Directory, be sure to <filename>kill</filename>
251 the BitBake server for that build area:
252 <literallayout class='monospaced'>
253 $ bitbake -m
254 </literallayout>
255 </para></listitem>
256 </orderedlist>
257 </para>
258
259 <para>
260 For information on how to use Toaster, see the
261 "<link linkend='using-the-toaster-interface'>Using the Toaster Interface</link>"
262 section.
263 </para>
264 </section>
265
266 <section id='setting-up-a-hosted-managed-mode-for-toaster'>
267 <title>Setting Up a Hosted Managed Mode for Toaster</title>
268
269 <para>
270 (RIGHT NOW, THE
271 <ulink url='https://wiki.yoctoproject.org/wiki/Setting_up_a_hosted_managed_mode_for_Toaster'>WIKI PAGE</ulink>
272 HAS SOME INFORMATION ON THIS.
273 I DON'T GET IT THOUGH.
274 I NEED SOME MORE INFORMATION IN ORDER TO UNDERSTAND THIS AND
275 CREATE A SECTION.
276 </para>
277 </section>
278
279 <section id='using-the-toaster-interface'>
280 <title>Using the Toaster Interface</title>
281
282 <para>
283 The Toaster interface allows you to examine the following:
284 <itemizedlist>
285 <listitem><para>
286 Outcome of the build, errors and warnings thrown
287 </para></listitem>
288 <listitem><para>
289 Packages included in an image
290 </para></listitem>
291 <listitem><para>
292 Image directory structure
293 </para></listitem>
294 <listitem><para>
295 Build configuration
296 </para></listitem>
297 <listitem><para>
298 Recipes and packages built
299 </para></listitem>
300 <listitem><para>
301 Full dependency chain for tasks, recipes and packages
302 </para></listitem>
303 <listitem><para>
304 Tasks run by the build system
305 </para></listitem>
306 <listitem><para>
307 Performance information such as time, CPU usage, and
308 disk I/O per task
309 </para></listitem>
310 </itemizedlist>
311 For several useful videos that show how to effectively use the
312 Toaster interface, see the
313 <ulink url='https://www.yoctoproject.org/documentation/toaster-manual-17'>Toaster Documentation</ulink>
314 on the Yocto Project website.
315 (SO WE NEED TO DECIDE IF THESE VIDS ARE GOING TO ROLL OVER INTO
316 1.8 AND REMAIN ON A "TOASTER MANUAL" PAGE AS THEY DO IN 1.7.
317 OR, IF WE ARE GOING TO GET THE LINKS TO THE VIDS HERE IN THIS
318 MANUAL.)
319 </para>
320 </section>
321</chapter>
322
323
324<!--
325vim: expandtab tw=80 ts=4
326-->
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 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='toaster-manual-start'>
6
7<title>Preparing to Use Toaster</title>
8
9 <para>
10 This chapter describes how you need to prepare your system in order to
11 use Toaster.
12 Toaster requires some packages that you must have installed before trying
13 to run Toaster.
14 </para>
15
16 <section id='toaster-setting-up-the-basic-system-requirements'>
17 <title>Setting Up the Basic System Requirements</title>
18
19 <para>
20 You first need to be sure your build system is set up to run
21 the Yocto Project.
22 See the
23 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>"
24 section in the Yocto Project Quick Start for information on how
25 to set up your system for the Yocto Project.
26 </para>
27 </section>
28
29 <section id='toaster-establishing-toaster-system-dependencies'>
30 <title>Establishing Toaster System Dependencies</title>
31
32 <para>
33 Toaster requires extra Python dependencies that Bitbake
34 does not need in order to run.
35 In order to make it easy to run Toaster, a requirements file
36 located in the root directory of
37 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
38 <filename>bitbake/</filename>
39 (e.g. <filename>poky/bitbake/toaster-requirements.txt</filename>).
40 The dependencies appear in a <filename>pip</filename>,
41 install-compatible format:
42 <literallayout class='monospaced'>
43 Django==1.6
44 South==0.8.4
45 argparse==1.2.1
46 wsgiref==0.1.2
47 </literallayout>
48 Follow these steps to get set up:
49 <orderedlist>
50 <listitem><para><emphasis>Create and activate a virtual environment:</emphasis>
51 <literallayout class='monospaced'>
52 $ virtualenv venv
53 $ source venv/bin/activate
54 </literallayout>
55 </para></listitem>
56 <listitem><para><emphasis>Use <filename>pip</filename> to install needed packages:</emphasis>
57 <literallayout class='monospaced'>
58 $ pip install -r bitbake/toaster-requirements.txt
59 </literallayout>
60 </para></listitem>
61 </orderedlist>
62 Once you complete these steps, you execute in a lightweight
63 "virtual environment” with its own site directories that are
64 optionally isolated from system site directories.
65 The virtual environment has its own Python binary
66 (allowing creation of environments with various Python versions)
67 and can have its own independent set of installed Python packages
68 in its site directories.
69 </para>
70 </section>
71
72</chapter>
73<!--
74vim: expandtab tw=80 ts=4
75-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-12 05:35:38 +0000