summaryrefslogtreecommitdiffstats
path: root/documentation/toaster-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/toaster-manual')
-rw-r--r--documentation/toaster-manual/toaster-manual-intro.xml4
-rw-r--r--documentation/toaster-manual/toaster-manual-setup-and-use.xml473
-rw-r--r--documentation/toaster-manual/toaster-manual-start.xml13
3 files changed, 479 insertions, 11 deletions
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 @@
39 <para> 39 <para>
40 You can use Toaster in Analysis Mode or Build Mode: 40 You can use Toaster in Analysis Mode or Build Mode:
41 <itemizedlist> 41 <itemizedlist>
42 <listitem><para><emphasis>Analysis Mode:</emphasis> 42 <listitem><para id='toaster-analysis-mode'><emphasis>Analysis Mode:</emphasis>
43 In Analysis Mode, you can record builds and statistics. 43 In Analysis Mode, you can record builds and statistics.
44 In this Mode, you directly access the 44 In this Mode, you directly access the
45 <filename>bitbake</filename> command, which you then use to 45 <filename>bitbake</filename> command, which you then use to
@@ -82,7 +82,7 @@
82 </para></listitem> 82 </para></listitem>
83 </itemizedlist> 83 </itemizedlist>
84 </para></listitem> 84 </para></listitem>
85 <listitem><para><emphasis>Build Mode:</emphasis> 85 <listitem><para id='toaster-build-mode'><emphasis>Build Mode:</emphasis>
86 In Build Mode, Toaster handles the build configuration, 86 In Build Mode, Toaster handles the build configuration,
87 scheduling and execution. 87 scheduling and execution.
88 In this mode, all your interaction with the build system 88 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 @@
6 6
7<title>Setting Up and Using Toaster</title> 7<title>Setting Up and Using Toaster</title>
8 8
9 <section id='using-toaster-in-analysis-mode'> 9 <section id='starting-toaster-for-local-development'>
10 <title>Starting Toaster for Local Development</title>
11
12 <para>
13 Once you have set up the Yocto Project and installed the
14 Toaster system dependencies as described in
15 "<link linkend='toaster-manual-start'>Preparing to Use Toaster</link>",
16 you are ready to start Toaster.
17 </para>
18
19 <para>
20 If you want to configure and start your builds using the
21 Toaster web interface
22 (i.e. "<link linkend='toaster-build-mode'>Build Mode</link>"),
23 navigate to the root of your
24 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
25 (e.g. <filename>poky</filename>):
26 <literallayout class='monospaced'>
27 $ cd poky
28 </literallayout>
29 Next, start Toaster:
30 <literallayout class='monospaced'>
31 $ bitbake/bin/toaster
32 </literallayout>
33 Open your favourite browser and enter the following:
34 <literallayout class='monospaced'>
35 http://127.0.0.1:8000
36 </literallayout>
37 If you would rather configure and start your builds
38 using the command line
39 (i.e. <link linkend='toaster-analysis-mode'>Analysis Mode</link>),
40 you can get Toaster to "listen"
41 to your builds and collect information about them.
42 To do that, navigate to the root of your Source Directory:
43 <literallayout class='monospaced'>
44 $ cd poky
45 </literallayout>
46 Once in that directory, source the build environment script:
47 <literallayout class='monospaced'>
48 $ source oe-init-build-env
49 </literallayout>
50 Next, from the build directory (e.g.
51 <filename>poky/build</filename>), start Toaster using this
52 command:
53 <literallayout class='monospaced'>
54 $ source ../bitbake/bin/toaster
55 </literallayout>
56 You can now run builds normally.
57 </para>
58
59 <para>
60 To see the build information provided by Toaster, open your
61 favorite browser and enter the following:
62 <literallayout class='monospaced'>
63 http://127.0.0.1:8000
64 </literallayout>
65 </para>
66 </section>
67
68 <section id='setting-a-different-port'>
69 <title>Setting a Different Port</title>
70
71 <para>
72 By default, Toaster starts on port 8000.
73 You can use the <filename>WEBPORT</filename> parameter to
74 set a different port.
75 For example, either of the following commands sets the
76 port to "8400":
77 <literallayout class='monospaced'>
78 $ bitbake/bin/toaster webport=8400
79 </literallayout>
80 or
81 <literallayout class='monospaced'>
82 $ source ../bitbake/bin/toaster webport=8400
83 </literallayout>
84 </para>
85 </section>
86
87 <section id='the-directory-for-cloning-layers'>
88 <title>The Directory for Cloning Layers</title>
89
90 <para>
91 If you are running Toaster in Build Mode, Toaster creates
92 a <filename>_toaster_clones</filename> directory inside
93 your Source Directory (i.e. <filename>poky</filename>).
94 For example, suppose you use this command to start Toaster:
95 <literallayout class='monospaced'>
96 poky/bitbake/bin/toaster
97 </literallayout>
98 In this example, Toaster creates and uses the
99 <filename>poky/_toaster_clones</filename>
100 directory to clone any layers needed for your builds.
101 </para>
102
103 <para>
104 Alternatively, if you would like all of your Toaster related
105 files and directories to be in a particular location other than
106 the default, you can set the <filename>TOASTER_DIR</filename>
107 environment variable, which takes precedence over your current
108 working directory.
109 Setting this environment variable causes Toaster to create and use
110 <filename>$TOASTER_DIR./_toaster_clones</filename>.
111 </para>
112 </section>
113
114 <section id='toaster-the-build-directory'>
115 <title>The Build Directory</title>
116
117 <para>
118 If you are running Toaster in Build Mode, Toaster creates a
119 build directory within your Source Directory (e.g.
120 <filename>poky</filename>).
121 For example, suppose you use this command to start Toaster:
122 <literallayout class='monospaced'>
123 poky/bitbake/bin/toaster
124 </literallayout>
125 In this example, Toaster creates and uses the
126 <filename>poky/_toaster_clones</filename>
127 directory to execute the builds.
128 </para>
129
130 <para>
131 Alternatively, if you would like all of your Toaster related files
132 and directories to be in a particular location, you can set
133 the <filename>TOASTER_DIR</filename> environment variable,
134 which takes precedence over your current working directory.
135 Setting this environment variable causes Toaster to use
136 <filename>$TOASTER_DIR./build</filename> as the build directory.
137 </para>
138 </section>
139
140 <section id='toaster-creating-a-django-super-user'>
141 <title>Creating a Django Superuser</title>
142
143 <para>
144 Toaster is built on the Django framework.
145 Django provides an administration interface you can use
146 to edit Toaster configuration parameters.
147 </para>
148
149 <para>
150 To access the Django administration interface, you must
151 create a superuser by following these steps:
152 <orderedlist>
153 <listitem><para>
154 If you used <filename>virtualenv</filename>, which is
155 recommended, to set up the Toaster system dependencies,
156 you need be sure the virtual environment is activated.
157 To activate this environment, use the following:
158 <literallayout class='monospaced'>
159 $ source venv/bin/activate
160 </literallayout>
161 </para></listitem>
162 <listitem><para>
163 From the root of your checkout directory, invoke the
164 following command from <filename>manage.py</filename>:
165 <literallayout class='monospaced'>
166 $ ./bitbake/lib/toaster/manage.py createsuperuser
167 </literallayout>
168 </para></listitem>
169 <listitem><para>
170 Django prompts you for the username, which you need to
171 provide.
172 </para></listitem>
173 <listitem><para>
174 Django prompts you for an email address, which is
175 optional.
176 </para></listitem>
177 <listitem><para>
178 Django prompts you for a password, which you must provide.
179 </para></listitem>
180 <listitem><para>
181 Django prompts you to re-enter your password for verification.
182 </para></listitem>
183 </orderedlist>
184 After completing these steps, the following confirmation message
185 appears:
186 <literallayout class='monospaced'>
187 Superuser created successfully.
188 </literallayout>
189 </para>
190
191 <para>
192 Creating a superuser allows you to access the Django administration
193 interface through a browser.
194 The URL for this interface is the same as the URL used for the
195 Toaster instance with "/admin" on the end.
196 For example, if you are running Toaster locally, use the
197 following URL:
198 <literallayout class='monospaced'>
199 http://127.0.0.1:8000/admin
200 </literallayout>
201 You can use the Django administration interface to set Toaster
202 configuration parameters such as the build directory, layer sources,
203 default variable values, and BitBake versions.
204 </para>
205 </section>
206
207 <section id='toaster-setting-up-a-production-instance-of-toaster'>
208 <title>Setting Up a Production Instance of Toaster</title>
209
210 <para>
211 You can use a production instance of Toaster to share the
212 Toaster instance with remote users, multiple users, or both.
213 The production instance is also the setup that can cope with
214 heavier loads on the web service.
215 Use the instructions in the following sections to set up
216 Toaster in
217 <link linkend='toaster-build-mode'>Build Mode</link>
218 where builds and projects are run,
219 viewed, and defined through the Toaster web interface.
220 </para>
221
222 <section id='toaster-production-instance-requirements'>
223 <title>Requirements</title>
224
225 <para>
226 Be sure you meet the following requirements:
227 <note>
228 You must comply with all Apache,
229 <filename>mod-wsgi</filename>, and Mysql requirements.
230 </note>
231 <itemizedlist>
232 <listitem><para>
233 Have all the build requirements as described in
234 "<link linkend='toaster-setting-up-the-basic-system-requirements'>Setting Up the Basic System Requirements</link>"
235 chapter.
236 </para></listitem>
237 <listitem><para>
238 Have an Apache webserver.
239 </para></listitem>
240 <listitem><para>
241 Have <filename>mod-wsgi</filename> for the Apache
242 webserver.
243 </para></listitem>
244 <listitem><para>
245 Use the Mysql database server.
246 </para></listitem>
247 <listitem><para>
248 If you are using Ubuntu 14.04.3, run the following:
249 <literallayout class='monospaced'>
250 $ sudo apt-get install apache2 libapache2-mod-wsgi mysql-server virtualenv libmysqlclient-dev
251 </literallayout>
252 </para></listitem>
253 <listitem><para>
254 If you are using Fedora 22 or a RedHat distribution, run
255 the following:
256 <literallayout class='monospaced'>
257 $ sudo dnf install httpd mod_wsgi python-virtualenv gcc mysql-devel
258 </literallayout>
259 </para></listitem>
260 </itemizedlist>
261 </para>
262 </section>
263
264 <section id='toaster-installation-steps'>
265 <title>Installation</title>
266
267 <para>
268 Perform the following steps to install Toaster:
269 <orderedlist>
270 <listitem><para>
271 Checkout a copy of <filename>poky</filename>
272 into the web server directory.
273 You will be using <filename>/var/www/toaster</filename>:
274 <literallayout class='monospaced'>
275 $ mkdir -p /var/www/toaster
276 $ cd /var/www/toaster/
277 $ git clone git://git.yoctoproject.org/poky
278 $ git checkout &DISTRO_NAME;
279 </literallayout>
280 </para></listitem>
281 <listitem><para>
282 Initialize a virtual environment and install Toaster
283 dependencies.
284 Using a virtual environment keeps the Python packages
285 isolated from your system-provided packages:
286 <literallayout class='monospaced'>
287 $ cd /var/www/toaster/
288 $ virtualenv venv
289 $ source ./venv/bin/activate
290 $ pip install -r ./poky/bitbake/toaster-requirements.txt
291 $ pip install mysql
292 $ pip install MySQL-python
293 </literallayout>
294 <note>
295 Isolating these packages is not required but is
296 recommended.
297 Alternatively, you can use your operating system's
298 package manager to install the packages.
299 </note>
300 </para></listitem>
301 <listitem><para>
302 Configure Toaster by editing
303 <filename>/var/www/toaster/poky/bitbake/lib/toaster/toastermain/settings.py</filename>
304 as follows:
305 <itemizedlist>
306 <listitem><para>
307 Edit the <filename>DATABASE</filename> settings:
308 <literallayout class='monospaced'>
309 DATABASES = {
310 'default': {
311 'ENGINE': 'django.db.backends.mysql',
312 'NAME': 'toaster_data',
313 'USER': 'toaster',
314 'PASSWORD': 'yourpasswordhere',
315 'HOST': 'localhost',
316 'PORT': '3306',
317 }
318 </literallayout>
319 </para></listitem>
320 <listitem><para>
321 Edit the <filename>SECRET_KEY</filename>:
322 <literallayout class='monospaced'>
323 SECRET_KEY = '<replaceable>your_secret_key</replaceable>'
324 </literallayout>
325 </para></listitem>
326 <listitem><para>
327 Edit the <filename>STATIC_ROOT</filename>:
328 <literallayout class='monospaced'>
329 STATIC_ROOT = '/var/www/toaster/static_files/'
330 </literallayout>
331 </para></listitem>
332 <listitem><para>
333 Enable Build Mode by adding the following
334 line to <filename>settings.py</filename>:
335 <literallayout class='monospaced'>
336 BUILD_MODE=True
337 </literallayout>
338 </para></listitem>
339 </itemizedlist>
340 </para></listitem>
341 <listitem><para>
342 Add the database and user to the <filename>mysql</filename>
343 server defined earlier:
344 <literallayout class='monospaced'>
345 $ mysql -u root -p
346 mysql> CREATE DATABASE toaster;
347 mysql> CREATE USER 'toaster'@'localhost' identified by 'yourpasswordhere';
348 mysql> GRANT all on toaster_data.* to 'toaster'@'localhost';
349 mysql> quit
350 </literallayout>
351 </para></listitem>
352 <listitem><para>
353 Get Toaster to create the database schema,
354 default data, and gather the statically-served files:
355 <literallayout class='monospaced'>
356 $ cd /var/www/toaster/poky/
357 $ ./bitbake/lib/toaster/manage.py syncdb --migrate
358 $ ./bitbake/lib/toaster/manage.py loadconf ./meta-yocto/conf/toasterconf.json
359 $ ./bitbake/lib/toaster/manage.py lsupdates
360 $ ./bitbake/lib/toaster/manage.py collectstatic
361 </literallayout>
362 </para>
363
364 <para>
365 For the above set of commands, after moving to the
366 <filename>poky</filename> directory,
367 the <filename>syncdb</filename> command with the
368 <filename>migrate</filename> option makes sure the database
369 schema has had changes propagated correctly (i.e.
370 migrations).
371 See the
372 <ulink url='https://south.readthedocs.org/en/latest/commands.html#syncdb'><filename>syncdb</filename></ulink>
373 command for more information.
374 </para>
375
376 <para>
377 The
378 <link linkend='toaster-command-loadconf'><filename>loadconf</filename></link>
379 command loads the
380 <filename>./meta-yocto/conf/toasterconf.json</filename>
381 JSON file.
382 </para>
383
384 <para>
385 The <filename>lsupdates</filename> command fetches the
386 initial recipes and layers data from the layer index.
387 </para>
388
389 <para>
390 Finally, the <filename>collectstatic</filename> command
391 is a Django framework command that collects all the
392 statically served files into a designated directory to
393 be served up by the Apache web server.
394 For more information on this Django command, see
395 <ulink url='https://docs.djangoproject.com/en/1.7/ref/contrib/staticfiles/'></ulink>.
396 </para></listitem>
397 <listitem><para>
398 Add an Apache configuration file for Toaster to your Apache web
399 server's configuration directory.
400 If you are using Ubuntu or Debian, put the file here:
401 <literallayout class='monospaced'>
402 /etc/apache2/conf-available/toaster.conf
403 </literallayout>
404 If you are using Fedora or RedHat, put it here:
405 <literallayout class='monospaced'>
406 /etc/httpd/conf.d/toaster.conf
407 </literallayout>
408 Following is a sample Apache configuration for Toaster
409 you can follow:
410 <literallayout class='monospaced'>
411 Alias /static /var/www/toaster/static_files
412 &lt;Directory /var/www/toaster/static_files&gt;
413 Order allow,deny
414 Allow from all
415 Require all granted
416 &lt;/Directory&gt;
417
418 WSGIDaemonProcess toaster_wsgi python-path=/var/www/toaster/poky/bitbake/lib/toaster:/var/www/toaster/venv/lib/python2.7/site-packages
419
420 WSGIScriptAlias / "/var/www/toaster/poky/bitbake/lib/toaster/toastermain/wsgi.py"
421 &lt;Location /&gt;
422 WSGIProcessGroup toastern_wsgi
423 &lt;/Location&gt;
424 </literallayout>
425 If you are using Ubuntu or Debian,
426 you will need to enable the config and module for Apache:
427 <literallayout class='monospaced'>
428 $ sudo a2enmod wsgi
429 $ sudo a2enconf toaster
430 </literallayout>
431 Finally, restart Apache to make sure all new configuration
432 is loaded.
433 For Ubuntu and Debian use:
434 <literallayout class='monospaced'>
435 $ sudo service apache2 restart
436 </literallayout>
437 For Fedora and RedHat use:
438 <literallayout class='monospaced'>
439 $ sudo service httpd restart
440 </literallayout>
441 </para></listitem>
442 <listitem><para>
443 Install the build runner service.
444 This service needs to be running in order to dispatch
445 builds.
446 Use this command:
447 <literallayout class='monospaced'>
448 /var/www/toaster/poky/bitbake/lib/toaster/manage.py runbuilds
449 </literallayout>
450 Here is an example:
451 <literallayout class='monospaced'>
452 #!/bin/sh
453 # toaster run builds dispatcher
454 cd /var/www/toaster/
455 source ./venv/bin/activate
456 ./bitbake/lib/toaster/manage.py runbuilds
457 </literallayout>
458 </para></listitem>
459 </orderedlist>
460 You can now open up a browser and start using Toaster.
461 </para>
462 </section>
463 </section>
464
465
466
467
468<!-- <section id='using-toaster-in-analysis-mode'>
10 <title>Using Toaster in Analysis Mode</title> 469 <title>Using Toaster in Analysis Mode</title>
11 470
471
12 <para> 472 <para>
13 This section describes how to use Toaster in Analysis Mode 473 This section describes how to use Toaster in Analysis Mode
14 after setting Toaster up as a local instance or as a hosted 474 after setting Toaster up as a local instance or as a hosted
@@ -324,14 +784,14 @@
324 <listitem><para><emphasis>Start the BitBake Server:</emphasis> 784 <listitem><para><emphasis>Start the BitBake Server:</emphasis>
325 Start the BitBake server using the following command: 785 Start the BitBake server using the following command:
326 <literallayout class='monospaced'> 786 <literallayout class='monospaced'>
327 $ bitbake --postread conf/toaster.conf --server-only -t xmlrpc -B localhost:0 &amp;&amp; export BBSERVER=localhost:-1 787 $ bitbake &dash;&dash;postread conf/toaster.conf &dash;&dash;server-only -t xmlrpc -B localhost:0 &amp;&amp; export BBSERVER=localhost:-1
328 </literallayout> 788 </literallayout>
329 </para></listitem> 789 </para></listitem>
330 <listitem><para><emphasis>Start the Logging Server:</emphasis> 790 <listitem><para><emphasis>Start the Logging Server:</emphasis>
331 Start the Toaster Logging Interface using the following 791 Start the Toaster Logging Interface using the following
332 command: 792 command:
333 <literallayout class='monospaced'> 793 <literallayout class='monospaced'>
334 $ nohup bitbake --observe-only -u toasterui >toaster_ui.log &amp; 794 $ nohup bitbake &dash;&dash;observe-only -u toasterui >toaster_ui.log &amp;
335 </literallayout> 795 </literallayout>
336 <note> 796 <note>
337 No hard-coded ports are used in the BitBake options 797 No hard-coded ports are used in the BitBake options
@@ -810,6 +1270,7 @@
810 </para> 1270 </para>
811 </section> 1271 </section>
812 </section> 1272 </section>
1273-->
813 1274
814 <section id='using-the-toaster-web-interface'> 1275 <section id='using-the-toaster-web-interface'>
815 <title>Using the Toaster Web Interface</title> 1276 <title>Using the Toaster Web Interface</title>
@@ -875,6 +1336,12 @@
875 <para> 1336 <para>
876 Following are several videos that show how to use the Toaster GUI: 1337 Following are several videos that show how to use the Toaster GUI:
877 <itemizedlist> 1338 <itemizedlist>
1339 <listitem><para><emphasis>Build Custom Layers:</emphasis>
1340 This
1341 <ulink url='https://www.youtube.com/watch?v=QJzaE_XjX5c'>video</ulink>
1342 shows you how to build custom layers that are used with
1343 Toaster.
1344 </para></listitem>
878 <listitem><para><emphasis>Build Configuration:</emphasis> 1345 <listitem><para><emphasis>Build Configuration:</emphasis>
879 This 1346 This
880 <ulink url='https://www.youtube.com/watch?v=qYgDZ8YzV6w'>video</ulink> 1347 <ulink url='https://www.youtube.com/watch?v=qYgDZ8YzV6w'>video</ulink>
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 @@
15 <title>Setting Up the Basic System Requirements</title> 15 <title>Setting Up the Basic System Requirements</title>
16 16
17 <para> 17 <para>
18 You first need to be sure your build system is set up to run 18 Before you can use Toaster, you need to first set up your
19 the Yocto Project. 19 build system to run the Yocto Project.
20 See the 20 To do this, follow the instructions in the
21 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>" 21 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>"
22 section in the Yocto Project Quick Start for information on how 22 and
23 to set up your system for the Yocto Project. 23 "<ulink url='&YOCTO_DOCS_QS_URL;#releases'>Yocto Project Release</ulink>"
24 sections in the Yocto Project Quick Start.
24 </para> 25 </para>
25 </section> 26 </section>
26 27
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-15 18:30:36 +0000