summaryrefslogtreecommitdiffstats
path: root/documentation/toaster-manual/toaster-manual-setup-and-use.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/toaster-manual/toaster-manual-setup-and-use.xml')
-rw-r--r--documentation/toaster-manual/toaster-manual-setup-and-use.xml844
1 files changed, 0 insertions, 844 deletions
diff --git a/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
deleted file mode 100644
index f555745923..0000000000
--- a/documentation/toaster-manual/toaster-manual-setup-and-use.xml
+++ /dev/null
@@ -1,844 +0,0 @@
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<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='toaster-manual-setup-and-use'>
7
8<title>Setting Up and Using Toaster</title>
9
10 <section id='starting-toaster-for-local-development'>
11 <title>Starting Toaster for Local Development</title>
12
13 <para>
14 Once you have set up the Yocto Project and installed the
15 Toaster system dependencies as described in the
16 "<link linkend='toaster-manual-start'>Preparing to Use Toaster</link>"
17 chapter, you are ready to start Toaster.
18 </para>
19
20 <para>
21 Navigate to the root of your
22 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
23 (e.g. <filename>poky</filename>):
24 <literallayout class='monospaced'>
25 $ cd poky
26 </literallayout>
27 Once in that directory, source the build environment script:
28 <literallayout class='monospaced'>
29 $ source oe-init-build-env
30 </literallayout>
31 Next, from the build directory (e.g.
32 <filename>poky/build</filename>), start Toaster using this
33 command:
34 <literallayout class='monospaced'>
35 $ source toaster start
36 </literallayout>
37 You can now run your builds from the command line, or with
38 Toaster as explained in section
39 "<link linkend='using-the-toaster-web-interface'>Using the Toaster Web Interface</link>".
40 </para>
41
42 <para>
43 To access the Toaster web interface, open your favorite
44 browser and enter the following:
45 <literallayout class='monospaced'>
46 http://127.0.0.1:8000
47 </literallayout>
48 </para>
49 </section>
50
51 <section id='setting-a-different-port'>
52 <title>Setting a Different Port</title>
53
54 <para>
55 By default, Toaster starts on port 8000.
56 You can use the <filename>WEBPORT</filename> parameter to
57 set a different port.
58 For example, the following command sets the port to "8400":
59 <literallayout class='monospaced'>
60 $ source toaster start webport=8400
61 </literallayout>
62 </para>
63 </section>
64
65 <section id='setting-up-toaster-without-a-web-server'>
66 <title>Setting Up Toaster Without a Web Server</title>
67
68 <para>
69 You can start a Toaster environment without starting its
70 web server. This is useful for the following:
71 <itemizedlist>
72 <listitem><para>
73 Capturing a command-line build's statistics into
74 the Toaster database for examination later.
75 </para></listitem>
76 <listitem><para>
77 Capturing a command-line build's statistics when
78 the Toaster server is already running.
79 </para></listitem>
80 <listitem><para>
81 Having one instance of the Toaster web server
82 track and capture multiple command-line builds,
83 where each build is started in its own "noweb"
84 Toaster environment.
85 </para></listitem>
86 </itemizedlist>
87 The following commands show how to start a Toaster environment
88 without starting its web server, perform BitBake operations,
89 and then shut down the Toaster environment.
90 Once the build is complete, you can close the Toaster environment.
91 Before closing the environment, however, you should allow a few
92 minutes to ensure the complete transfer of its BitBake build
93 statistics to the Toaster database.
94 If you have a separate Toaster web server instance running, you
95 can watch this command-line build's progress and examine the
96 results as soon as they are posted:
97 <literallayout class='monospaced'>
98 $ source toaster start noweb
99 $ bitbake <replaceable>target</replaceable>
100 $ source toaster stop
101 </literallayout>
102 </para>
103 </section>
104
105 <section id='setting-up-toaster-without-a-build-server'>
106 <title>Setting Up Toaster Without a Build Server</title>
107
108 <para>
109 You can start a Toaster environment with the
110 "New Projects" feature disabled.
111 Doing so is useful for the following:
112 <itemizedlist>
113 <listitem><para>
114 Sharing your build results over the web server while
115 blocking others from starting builds on your host.
116 </para></listitem>
117 <listitem><para>
118 Allowing only local command-line builds to be captured
119 into the Toaster database.
120 </para></listitem>
121 </itemizedlist>
122 Use the following command to set up Toaster without a
123 build server:
124 <literallayout class='monospaced'>
125 $ source toaster start nobuild webport=<replaceable>port</replaceable>
126 </literallayout>
127 </para>
128 </section>
129
130 <section id='setting-up-external-access'>
131 <title>Setting up External Access</title>
132
133 <para>
134 By default, Toaster binds to the loop back address
135 (i.e. localhost), which does not allow access from
136 external hosts. To allow external access, use the
137 <filename>WEBPORT</filename> parameter to open an
138 address that connects to the network, specifically the
139 IP address that your NIC uses to connect to the network.
140 You can also bind to all IP addresses the computer
141 supports by using the shortcut
142 "0.0.0.0:<replaceable>port</replaceable>".
143 </para>
144
145 <para>
146 The following example binds to all IP addresses on the
147 host:
148 <literallayout class='monospaced'>
149 $ source toaster start webport=0.0.0.0:8400
150 </literallayout>
151 This example binds to a specific IP address on the host's
152 NIC:
153 <literallayout class='monospaced'>
154 $ source toaster start webport=192.168.1.1:8400
155 </literallayout>
156 </para>
157 </section>
158
159 <section id='the-directory-for-cloning-layers'>
160 <title>The Directory for Cloning Layers</title>
161
162 <para>
163 Toaster creates a <filename>_toaster_clones</filename>
164 directory inside your Source Directory
165 (i.e. <filename>poky</filename>) to clone any layers
166 needed for your builds.
167 </para>
168
169 <para>
170 Alternatively, if you would like all of your Toaster related
171 files and directories to be in a particular location other than
172 the default, you can set the <filename>TOASTER_DIR</filename>
173 environment variable, which takes precedence over your current
174 working directory.
175 Setting this environment variable causes Toaster to create and use
176 <filename>$TOASTER_DIR./_toaster_clones</filename>.
177 </para>
178 </section>
179
180 <section id='toaster-the-build-directory'>
181 <title>The Build Directory</title>
182
183 <para>
184 Toaster creates a build directory within your Source
185 Directory (e.g. <filename>poky</filename>) to execute
186 the builds.
187 </para>
188
189 <para>
190 Alternatively, if you would like all of your Toaster related files
191 and directories to be in a particular location, you can set
192 the <filename>TOASTER_DIR</filename> environment variable,
193 which takes precedence over your current working directory.
194 Setting this environment variable causes Toaster to use
195 <filename>$TOASTER_DIR/build</filename> as the build directory.
196 </para>
197 </section>
198
199 <section id='toaster-creating-a-django-super-user'>
200 <title>Creating a Django Superuser</title>
201
202 <para>
203 Toaster is built on the
204 <ulink url='https://www.djangoproject.com/'>Django framework</ulink>.
205 Django provides an administration interface you can use
206 to edit Toaster configuration parameters.
207 </para>
208
209 <para>
210 To access the Django administration interface, you must
211 create a superuser by following these steps:
212 <orderedlist>
213 <listitem><para>
214 If you used <filename>pip3</filename>, which is
215 recommended, to set up the Toaster system dependencies,
216 you need be sure the local user path is in your
217 <filename>PATH</filename> list.
218 To append the pip3 local user path, use the following
219 command:
220 <literallayout class='monospaced'>
221 $ export PATH=$PATH:$HOME/.local/bin
222 </literallayout>
223 </para></listitem>
224 <listitem><para>
225 From the directory containing the Toaster database,
226 which by default is the
227 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
228 invoke the <filename>createsuperuser</filename> command
229 from <filename>manage.py</filename>:
230 <literallayout class='monospaced'>
231 $ cd ~/poky/build
232 $ ../bitbake/lib/toaster/manage.py createsuperuser
233 </literallayout>
234 </para></listitem>
235 <listitem><para>
236 Django prompts you for the username, which you need to
237 provide.
238 </para></listitem>
239 <listitem><para>
240 Django prompts you for an email address, which is
241 optional.
242 </para></listitem>
243 <listitem><para>
244 Django prompts you for a password, which you must provide.
245 </para></listitem>
246 <listitem><para>
247 Django prompts you to re-enter your password for verification.
248 </para></listitem>
249 </orderedlist>
250 After completing these steps, the following confirmation message
251 appears:
252 <literallayout class='monospaced'>
253 Superuser created successfully.
254 </literallayout>
255 </para>
256
257 <para>
258 Creating a superuser allows you to access the Django administration
259 interface through a browser.
260 The URL for this interface is the same as the URL used for the
261 Toaster instance with "/admin" on the end.
262 For example, if you are running Toaster locally, use the
263 following URL:
264 <literallayout class='monospaced'>
265 http://127.0.0.1:8000/admin
266 </literallayout>
267 You can use the Django administration interface to set Toaster
268 configuration parameters such as the build directory, layer sources,
269 default variable values, and BitBake versions.
270 </para>
271 </section>
272
273 <section id='toaster-setting-up-a-production-instance-of-toaster'>
274 <title>Setting Up a Production Instance of Toaster</title>
275
276 <para>
277 You can use a production instance of Toaster to share the
278 Toaster instance with remote users, multiple users, or both.
279 The production instance is also the setup that can handle
280 heavier loads on the web service.
281 Use the instructions in the following sections to set up
282 Toaster to run builds through the Toaster web interface.
283 </para>
284
285 <section id='toaster-production-instance-requirements'>
286 <title>Requirements</title>
287
288 <para>
289 Be sure you meet the following requirements:
290 <note>
291 You must comply with all Apache,
292 <filename>mod-wsgi</filename>, and Mysql requirements.
293 </note>
294 <itemizedlist>
295 <listitem><para>
296 Have all the build requirements as described in the
297 "<link linkend='toaster-manual-start'>Preparing to Use Toaster</link>"
298 chapter.
299 </para></listitem>
300 <listitem><para>
301 Have an Apache webserver.
302 </para></listitem>
303 <listitem><para>
304 Have <filename>mod-wsgi</filename> for the Apache
305 webserver.
306 </para></listitem>
307 <listitem><para>
308 Use the Mysql database server.
309 </para></listitem>
310 <listitem><para>
311 If you are using Ubuntu 16.04, run the following:
312 <literallayout class='monospaced'>
313 $ sudo apt-get install apache2 libapache2-mod-wsgi-py3 mysql-server python3-pip libmysqlclient-dev
314 </literallayout>
315 </para></listitem>
316 <listitem><para>
317 If you are using Fedora 24 or a RedHat distribution, run
318 the following:
319 <literallayout class='monospaced'>
320 $ sudo dnf install httpd python3-mod_wsgi python3-pip mariadb-server mariadb-devel python3-devel
321 </literallayout>
322 </para></listitem>
323 <listitem><para>
324 If you are using openSUSE Leap 42.1, run
325 the following:
326 <literallayout class='monospaced'>
327 $ sudo zypper install apache2 apache2-mod_wsgi-python3 python3-pip mariadb mariadb-client python3-devel
328 </literallayout>
329 </para></listitem>
330 </itemizedlist>
331 </para>
332 </section>
333
334 <section id='toaster-installation-steps'>
335 <title>Installation</title>
336
337 <para>
338 Perform the following steps to install Toaster:
339 <orderedlist>
340 <listitem><para>
341 Create toaster user and set its home directory to
342 <filename>/var/www/toaster</filename>:
343 <literallayout class='monospaced'>
344 $ sudo /usr/sbin/useradd toaster -md /var/www/toaster -s /bin/false
345 $ sudo su - toaster -s /bin/bash
346 </literallayout>
347 </para></listitem>
348 <listitem><para>
349 Checkout a copy of <filename>poky</filename>
350 into the web server directory.
351 You will be using <filename>/var/www/toaster</filename>:
352 <literallayout class='monospaced'>
353 $ git clone git://git.yoctoproject.org/poky
354 $ git checkout &DISTRO_NAME_NO_CAP;
355 </literallayout>
356 </para></listitem>
357 <listitem><para>
358 Install Toaster
359 dependencies using the --user flag which
360 keeps the Python packages
361 isolated from your system-provided packages:
362 <literallayout class='monospaced'>
363 $ cd /var/www/toaster/
364 $ pip3 install --user -r ./poky/bitbake/toaster-requirements.txt
365 $ pip3 install --user mysqlclient
366 </literallayout>
367 <note>
368 Isolating these packages is not required but is
369 recommended.
370 Alternatively, you can use your operating system's
371 package manager to install the packages.
372 </note>
373 </para></listitem>
374 <listitem><para>
375 Configure Toaster by editing
376 <filename>/var/www/toaster/poky/bitbake/lib/toaster/toastermain/settings.py</filename>
377 as follows:
378 <itemizedlist>
379 <listitem><para>
380 Edit the
381 <ulink url='https://docs.djangoproject.com/en/1.11/ref/settings/#databases'>DATABASES</ulink>
382 settings:
383 <literallayout class='monospaced'>
384 DATABASES = {
385 'default': {
386 'ENGINE': 'django.db.backends.mysql',
387 'NAME': 'toaster_data',
388 'USER': 'toaster',
389 'PASSWORD': 'yourpasswordhere',
390 'HOST': 'localhost',
391 'PORT': '3306',
392 }
393 }
394 </literallayout>
395 </para></listitem>
396 <listitem><para>
397 Edit the
398 <ulink url='https://docs.djangoproject.com/en/1.11/ref/settings/#std:setting-SECRET_KEY'>SECRET_KEY</ulink>:
399 <literallayout class='monospaced'>
400 SECRET_KEY = '<replaceable>your_secret_key</replaceable>'
401 </literallayout>
402 </para></listitem>
403 <listitem><para>
404 Edit the
405 <ulink url='https://docs.djangoproject.com/en/1.11/ref/settings/#std:setting-STATIC_ROOT'>STATIC_ROOT</ulink>:
406 <literallayout class='monospaced'>
407 STATIC_ROOT = '/var/www/toaster/static_files/'
408 </literallayout>
409 </para></listitem>
410 </itemizedlist>
411 </para></listitem>
412 <listitem><para>
413 Add the database and user to the <filename>mysql</filename>
414 server defined earlier:
415 <literallayout class='monospaced'>
416 $ mysql -u root -p
417 mysql> CREATE DATABASE toaster_data;
418 mysql> CREATE USER 'toaster'@'localhost' identified by 'yourpasswordhere';
419 mysql> GRANT all on toaster_data.* to 'toaster'@'localhost';
420 mysql> quit
421 </literallayout>
422 </para></listitem>
423 <listitem><para>
424 Get Toaster to create the database schema,
425 default data, and gather the statically-served files:
426 <literallayout class='monospaced'>
427 $ cd /var/www/toaster/poky/
428 $ ./bitbake/lib/toaster/manage.py migrate
429 $ TOASTER_DIR=`pwd` TEMPLATECONF='poky' \
430 ./bitbake/lib/toaster/manage.py checksettings
431 $ ./bitbake/lib/toaster/manage.py collectstatic
432 </literallayout>
433 In the previous example, from the <filename>poky</filename>
434 directory, the <filename>migrate</filename> command
435 ensures the database schema changes have propagated
436 correctly (i.e. migrations).
437 The next line sets the Toaster root directory
438 <filename>TOASTER_DIR</filename> and the location
439 of the Toaster configuration file
440 <filename>TOASTER_CONF</filename>, which is relative to
441 <filename>TOASTER_DIR</filename>.
442 The <filename>TEMPLATECONF</filename> value reflects the
443 contents of <filename>poky/.templateconf</filename>, and
444 by default, should include the string "poky".
445 For more information on the Toaster configuration
446 file, see the
447 "<link linkend='configuring-toaster'>Configuring Toaster</link>"
448 section.</para>
449
450 <para>This line also runs the <filename>checksettings</filename>
451 command, which configures the location of the Toaster
452 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
453 The Toaster root directory <filename>TOASTER_DIR</filename>
454 determines where the Toaster build directory
455 is created on the file system.
456 In the example above,
457 <filename>TOASTER_DIR</filename> is set as follows:
458 <literallayout class="monospaced">
459 /var/www/toaster/poky
460 </literallayout>
461 This setting causes the Toaster build directory to be:
462 <literallayout class="monospaced">
463 /var/www/toaster/poky/build
464 </literallayout></para>
465
466 <para>Finally, the <filename>collectstatic</filename> command
467 is a Django framework command that collects all the
468 statically served files into a designated directory to
469 be served up by the Apache web server as defined by
470 <filename>STATIC_ROOT</filename>.
471 </para></listitem>
472 <listitem><para>
473 Test and/or use the Mysql integration with Toaster's
474 Django web server.
475 At this point, you can start up the normal Toaster
476 Django web server with the Toaster database in Mysql.
477 You can use this web server to confirm that the database
478 migration and data population from the Layer Index is
479 complete.</para>
480
481 <para>To start the default Toaster Django web server with
482 the Toaster database now in Mysql, use the standard
483 start commands:
484 <literallayout class='monospaced'>
485 $ source oe-init-build-env
486 $ source toaster start
487 </literallayout>
488 Additionally, if Django is sufficient for your requirements,
489 you can use it for your release system and migrate later
490 to Apache as your requirements change.
491 </para></listitem>
492 <listitem><para>
493 Add an Apache configuration file for Toaster to your Apache web
494 server's configuration directory.
495 If you are using Ubuntu or Debian, put the file here:
496 <literallayout class='monospaced'>
497 /etc/apache2/conf-available/toaster.conf
498 </literallayout>
499 If you are using Fedora or RedHat, put it here:
500 <literallayout class='monospaced'>
501 /etc/httpd/conf.d/toaster.conf
502 </literallayout>
503 If you are using OpenSUSE, put it here:
504 <literallayout class='monospaced'>
505 /etc/apache2/conf.d/toaster.conf
506 </literallayout>
507 Following is a sample Apache configuration for Toaster
508 you can follow:
509 <literallayout class='monospaced'>
510 Alias /static /var/www/toaster/static_files
511 &lt;Directory /var/www/toaster/static_files&gt;
512 &lt;IfModule mod_access_compat.c&gt;
513 Order allow,deny
514 Allow from all
515 &lt;/IfModule&gt;
516 &lt;IfModule !mod_access_compat.c&gt;
517 Require all granted
518 &lt;/IfModule&gt;
519 &lt;/Directory&gt;
520
521 &lt;Directory /var/www/toaster/poky/bitbake/lib/toaster/toastermain&gt;
522 &lt;Files "wsgi.py"&gt;
523 Require all granted
524 &lt;/Files&gt;
525 &lt;/Directory&gt;
526
527 WSGIDaemonProcess toaster_wsgi python-path=/var/www/toaster/poky/bitbake/lib/toaster:/var/www/toaster/.local/lib/python3.4/site-packages
528
529 WSGIScriptAlias / "/var/www/toaster/poky/bitbake/lib/toaster/toastermain/wsgi.py"
530 &lt;Location /&gt;
531 WSGIProcessGroup toaster_wsgi
532 &lt;/Location&gt;
533 </literallayout>
534 If you are using Ubuntu or Debian,
535 you will need to enable the config and module for Apache:
536 <literallayout class='monospaced'>
537 $ sudo a2enmod wsgi
538 $ sudo a2enconf toaster
539 $ chmod +x bitbake/lib/toaster/toastermain/wsgi.py
540 </literallayout>
541 Finally, restart Apache to make sure all new configuration
542 is loaded.
543 For Ubuntu, Debian, and OpenSUSE use:
544 <literallayout class='monospaced'>
545 $ sudo service apache2 restart
546 </literallayout>
547 For Fedora and RedHat use:
548 <literallayout class='monospaced'>
549 $ sudo service httpd restart
550 </literallayout>
551 </para></listitem>
552 <listitem><para>
553 Prepare the systemd service to run Toaster builds.
554 Here is a sample configuration file for the service:
555 <literallayout class='monospaced'>
556 [Unit]
557 Description=Toaster runbuilds
558
559 [Service]
560 Type=forking
561 User=toaster
562 ExecStart=/usr/bin/screen -d -m -S runbuilds /var/www/toaster/poky/bitbake/lib/toaster/runbuilds-service.sh start
563 ExecStop=/usr/bin/screen -S runbuilds -X quit
564 WorkingDirectory=/var/www/toaster/poky
565
566 [Install]
567 WantedBy=multi-user.target
568 </literallayout>
569 Prepare the <filename>runbuilds-service.sh</filename>
570 script that you need to place in the
571 <filename>/var/www/toaster/poky/bitbake/lib/toaster/</filename>
572 directory by setting up executable permissions:
573 <literallayout class='monospaced'>
574 #!/bin/bash
575
576 #export http_proxy=http://proxy.host.com:8080
577 #export https_proxy=http://proxy.host.com:8080
578 #export GIT_PROXY_COMMAND=$HOME/bin/gitproxy
579
580 cd ~/poky/
581 source ./oe-init-build-env build
582 source ../bitbake/bin/toaster $1 noweb
583 [ "$1" == 'start' ] &amp;&amp; /bin/bash
584 </literallayout>
585 </para></listitem>
586 <listitem><para>
587 Run the service:
588 <literallayout class='monospaced'>
589 # service runbuilds start
590 </literallayout>
591 Since the service is running in a detached screen
592 session, you can attach to it using this command:
593 <literallayout class='monospaced'>
594 $ sudo su - toaster
595 $ screen -rS runbuilds
596 </literallayout>
597 You can detach from the service again using "Ctrl-a"
598 followed by "d" key combination.
599 </para></listitem>
600 </orderedlist>
601 You can now open up a browser and start using Toaster.
602 </para>
603 </section>
604 </section>
605
606 <section id='using-the-toaster-web-interface'>
607 <title>Using the Toaster Web Interface</title>
608
609 <para>
610 The Toaster web interface allows you to do the following:
611 <itemizedlist>
612 <listitem><para>
613 Browse published layers in the
614 <ulink url='http://layers.openembedded.org'>OpenEmbedded Layer Index</ulink>
615 that are available for your selected version of the build
616 system.
617 </para></listitem>
618 <listitem><para>
619 Import your own layers for building.
620 </para></listitem>
621 <listitem><para>
622 Add and remove layers from your configuration.
623 </para></listitem>
624 <listitem><para>
625 Set configuration variables.
626 </para></listitem>
627 <listitem><para>
628 Select a target or multiple targets to build.
629 </para></listitem>
630 <listitem><para>
631 Start your builds.
632 </para></listitem>
633 <listitem><para>
634 See what was built (recipes and packages) and what
635 packages were installed into your final image.
636 </para></listitem>
637 <listitem><para>
638 Browse the directory structure of your image.
639 </para></listitem>
640 <listitem><para>
641 See the value of all variables in your build configuration,
642 and which files set each value.
643 </para></listitem>
644 <listitem><para>
645 Examine error, warning and trace messages to aid in
646 debugging.
647 </para></listitem>
648 <listitem><para>
649 See information about the BitBake tasks executed and
650 reused during your build, including those that used
651 shared state.
652 </para></listitem>
653 <listitem><para>
654 See dependency relationships between recipes, packages
655 and tasks.
656 </para></listitem>
657 <listitem><para>
658 See performance information such as build time, task time,
659 CPU usage, and disk I/O.
660 </para></listitem>
661 </itemizedlist>
662 </para>
663
664 <section id='web-interface-videos'>
665 <title>Toaster Web Interface Videos</title>
666
667 <para>
668 Following are several videos that show how to use the Toaster GUI:
669 <itemizedlist>
670 <listitem><para><emphasis>Build Configuration:</emphasis>
671 This
672 <ulink url='https://www.youtube.com/watch?v=qYgDZ8YzV6w'>video</ulink>
673 overviews and demonstrates build configuration for Toaster.
674 </para></listitem>
675 <listitem><para><emphasis>Build Custom Layers:</emphasis>
676 This
677 <ulink url='https://www.youtube.com/watch?v=QJzaE_XjX5c'>video</ulink>
678 shows you how to build custom layers that are used with
679 Toaster.
680 </para></listitem>
681 <listitem><para><emphasis>Toaster Homepage and Table Controls:</emphasis>
682 This
683 <ulink url='https://www.youtube.com/watch?v=QEARDnrR1Xw'>video</ulink>
684 goes over the Toaster entry page, and provides
685 an overview of the data manipulation capabilities of
686 Toaster, which include search, sorting and filtering by
687 different criteria.
688 </para></listitem>
689 <listitem><para><emphasis>Build Dashboard:</emphasis>
690 This
691 <ulink url='https://www.youtube.com/watch?v=KKqHYcnp2gE'>video</ulink>
692 shows you the build dashboard, a page providing an
693 overview of the information available for a selected build.
694 </para></listitem>
695 <listitem><para><emphasis>Image Information:</emphasis>
696 This
697 <ulink url='https://www.youtube.com/watch?v=XqYGFsmA0Rw'>video</ulink>
698 walks through the information Toaster provides
699 about images: packages installed and root file system.
700 </para></listitem>
701 <listitem><para><emphasis>Configuration:</emphasis>
702 This
703 <ulink url='https://www.youtube.com/watch?v=UW-j-T2TzIg'>video</ulink>
704 provides Toaster build configuration information.
705 </para></listitem>
706 <listitem><para><emphasis>Tasks:</emphasis>
707 This
708 <ulink url='https://www.youtube.com/watch?v=D4-9vGSxQtw'>video</ulink>
709 shows the information Toaster provides about the
710 tasks run by the build system.
711 </para></listitem>
712 <listitem><para><emphasis>Recipes and Packages Built:</emphasis>
713 This
714 <ulink url='https://www.youtube.com/watch?v=x-6dx4huNnw'>video</ulink>
715 shows the information Toaster provides about recipes
716 and packages built.
717 </para></listitem>
718 <listitem><para><emphasis>Performance Data:</emphasis>
719 This
720 <ulink url='https://www.youtube.com/watch?v=qWGMrJoqusQ'>video</ulink>
721 shows the build performance data provided by
722 Toaster.
723 </para></listitem>
724 </itemizedlist>
725 </para>
726 </section>
727
728 <section id='a-note-on-the-local-yocto-project-release'>
729 <title>Additional Information About the Local Yocto Project Release</title>
730
731 <para>
732 This section only applies if you have set up Toaster
733 for local development, as explained in the
734 "<link linkend='starting-toaster-for-local-development'>Starting Toaster for Local Development</link>"
735 section.
736 </para>
737
738 <para>
739 When you create a project in Toaster, you will be asked to
740 provide a name and to select a Yocto Project release.
741 One of the release options you will find is called
742 "Local Yocto Project".
743 <imagedata fileref="figures/new-project.png" align="center" width="9in" />
744 </para>
745
746 <para>
747 When you select the "Local Yocto Project" release, Toaster
748 will run your builds using the local Yocto
749 Project clone you have in your computer: the same clone
750 you are using to run Toaster.
751 Unless you manually update
752 this clone, your builds will always use the same Git revision.
753 </para>
754
755 <para>
756 If you select any of the other release options, Toaster
757 will fetch the tip of your selected release from the upstream
758 <ulink url='https://git.yoctoproject.org'>Yocto Project repository</ulink>
759 every time you run a build.
760 Fetching this tip effectively
761 means that if your selected release is updated upstream, the
762 Git revision you are using for your builds will change.
763 If you are doing development locally, you might not want this
764 change to happen.
765 In that case, the "Local Yocto Project"
766 release might be the right choice.
767 </para>
768
769 <para>
770 However, the "Local Yocto Project" release
771 will not provide you with any compatible layers, other than the
772 three core layers that come with the Yocto Project:
773 <itemizedlist>
774 <listitem><para>
775 <ulink url='http://layers.openembedded.org/layerindex/branch/master/layer/openembedded-core/'>openembedded-core</ulink>
776 </para></listitem>
777 <listitem><para>
778 <ulink url='http://layers.openembedded.org/layerindex/branch/master/layer/meta-poky/'>meta-poky</ulink>
779 </para></listitem>
780 <listitem><para>
781 <ulink url='http://layers.openembedded.org/layerindex/branch/master/layer/meta-yocto-bsp/'>meta-yocto-bsp</ulink>
782 </para></listitem>
783 </itemizedlist>
784 <imagedata fileref="figures/compatible-layers.png" align="center" width="9in" />
785 </para>
786
787 <para>
788 If you want to build any other layers, you will need to
789 manually import them into your Toaster project, using the
790 "Import layer" page.
791 <imagedata fileref="figures/import-layer.png" align="center" width="9in" />
792 </para>
793
794 </section>
795
796 <section id='toaster-web-interface-preferred-version'>
797 <title>Building a Specific Recipe Given Multiple Versions</title>
798
799 <para>
800 Occasionally, a layer might provide more than one version of
801 the same recipe.
802 For example, the <filename>openembedded-core</filename> layer
803 provides two versions of the <filename>bash</filename> recipe
804 (i.e. 3.2.48 and 4.3.30-r0) and two versions of the
805 <filename>which</filename> recipe (i.e. 2.21 and 2.18).
806 The following figure shows this exact scenario:
807 <imagedata fileref="figures/bash-oecore.png" align="center" width="9in" depth="6in" />
808 </para>
809
810 <para>
811 By default, the OpenEmbedded build system builds one of the
812 two recipes.
813 For the <filename>bash</filename> case, version 4.3.30-r0 is
814 built by default.
815 Unfortunately, Toaster as it exists, is not able to override
816 the default recipe version.
817 If you would like to build bash 3.2.48, you need to set the
818 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink>
819 variable.
820 You can do so from Toaster, using the "Add variable" form,
821 which is available in the "BitBake variables" page of the
822 project configuration section as shown in the following screen:
823 <imagedata fileref="figures/add-variable.png" align="center" width="9in" depth="6in" />
824 </para>
825
826 <para>
827 To specify <filename>bash</filename> 3.2.48 as the version to build,
828 enter "PREFERRED_VERSION_bash" in the "Variable" field, and "3.2.48"
829 in the "Value" field.
830 Next, click the "Add variable" button:
831 <imagedata fileref="figures/set-variable.png" align="center" width="9in" depth="6in" />
832 </para>
833
834 <para>
835 After clicking the "Add variable" button, the settings for
836 <filename>PREFERRED_VERSION</filename> are added to the bottom
837 of the BitBake variables list.
838 With these settings, the OpenEmbedded build system builds the
839 desired version of the recipe rather than the default version:
840 <imagedata fileref="figures/variable-added.png" align="center" width="9in" depth="6in" />
841 </para>
842 </section>
843 </section>
844</chapter>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-13 20:12:34 +0000