summaryrefslogtreecommitdiffstats
path: root/documentation/toaster-manual/toaster-manual-reference.xml
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2015-02-18 06:24:18 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2015-04-01 12:59:10 +0100
commit85a0b9b941fbd38d44e4802a27290ad9ec4bb963 (patch)
tree92bf61d40674f0b28fd44af49daa38b215de3b73 /documentation/toaster-manual/toaster-manual-reference.xml
parent9e4adec98db325112ca7a8b9dd95722d4d0ab642 (diff)
downloadpoky-85a0b9b941fbd38d44e4802a27290ad9ec4bb963.tar.gz
toaster-manual: Draft of Manual.
Fixes [YOCTO #6901] (From yocto-docs rev: 258b46b0f3e23045b5fb8c97d03dceb69db5ce20) 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/toaster-manual-reference.xml')
-rw-r--r--documentation/toaster-manual/toaster-manual-reference.xml1069
1 files changed, 1069 insertions, 0 deletions
diff --git a/documentation/toaster-manual/toaster-manual-reference.xml b/documentation/toaster-manual/toaster-manual-reference.xml
new file mode 100644
index 0000000000..05184fa1eb
--- /dev/null
+++ b/documentation/toaster-manual/toaster-manual-reference.xml
@@ -0,0 +1,1069 @@
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-reference'>
6
7<title>Concepts and Reference</title>
8
9 <para>
10 In order to configure and use Toaster, you should understand some
11 concepts and have some basic command reference material available.
12 This final chapter provides conceptual information on layer sources,
13 releases, and JSON configuration files.
14 Also provided is a quick look at some useful
15 <filename>manage.py</filename> commands.
16 Information on <filename>manage.py</filename> commands does exist
17 across the Web and the information in this manual by no means
18 attempts to provide a command reference.
19 However, having relevant command useful for the Toaster context
20 is helpful.
21 </para>
22
23 <section id='layer-source'>
24 <title>Layer Source</title>
25
26 <para>
27 In general, a layer source is some source of existing layers.
28 In particular, we are concerned with layers that you can use
29 with the Yocto Project and Toaster.
30 This chapter describes a particular type of layer source called
31 a "layer index."
32 </para>
33
34 <para>
35 A layer index is a web application that contains information
36 about a set of custom layers.
37 A good example of an existing layer index is the
38 OpenEmbedded Metadata Index.
39 A public instance of this layer index exists at
40 <ulink url='http://layers.openembedded.org'></ulink>.
41 You can find the code for this layer index's web application at
42 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/layerindex-web/'></ulink>.
43 </para>
44
45 <para>
46 When you tie a layer source into Toaster, it can query the layer
47 source through a
48 <ulink url='http://en.wikipedia.org/wiki/Representational_state_transfer'>REST</ulink>
49 API, store the information about the layers in the Toaster
50 database, and then show the information to users.
51 Users are then able to view that information and build layers
52 from Toaster itself without worrying about cloning or editing
53 the BitBake layers configuration file
54 <filename>bblayers.conf</filename>.
55 </para>
56
57 <para>
58 Tying a layer source into Toaster is convenient when you have
59 many custom layers that need to be built on a regular basis by
60 a community of developers.
61 In fact, Toaster comes pre-configured with the OpenEmbedded
62 Metadata Index.
63 <note>
64 You do not have to use a layer source to use Toaster.
65 Tying into a layer source is optional.
66 </note>
67 </para>
68
69 <section id='layer-source-using-with-toaster'>
70 <title>Setting Up and Using a Layer Source</title>
71
72 <para>
73 To use your own layer source, you need to set up the layer
74 source and then tie it into Toaster.
75 This section describes how to tie into a layer index in a manner
76 similar to the way Toaster ties into the OpenEmbedded Metadata
77 Index.
78 </para>
79
80 <section id='understanding-your-layers'>
81 <title>Understanding Your Layers</title>
82
83 <para>
84 The obvious first step for using a layer index is to have
85 several custom layers that developers build and access using
86 the Yocto Project on a regular basis.
87 This set of layers needs to exist and you need to be
88 familiar with where they reside.
89 You will need that information when you set up the
90 code for the web application that "hooks" into your set of
91 layers.
92 </para>
93
94 <para>
95 For general information on layers, see the
96 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
97 and
98 "<ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>Using the Yocto Project's BSP Tools</ulink>"
99 sections in the Yocto Project Board Support Package (BSP)
100 Developer's Guide.
101 </para>
102 </section>
103
104 <section id='configuring-toaster-to-hook-into-your-layer-source'>
105 <title>Configuring Toaster to Hook Into Your Layer Index</title>
106
107 <para>
108 If you want Toaster to use your layer index, you must host
109 the web application in a server to which Toaster can
110 connect.
111 You also need to give Toaster the information about your
112 layer index.
113 In other words, you have to configure Toaster to use your
114 layer index.
115 This section describes two methods by which you can
116 configure and use your layer index.
117 </para>
118
119 <para>
120 In the previous section, the code for the OpenEmbedded
121 Metadata Index (i.e.
122 <ulink url='http://layers.openembedded.org'></ulink>) was
123 referenced.
124 You can use this code, which is at
125 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/layerindex-web/'></ulink>,
126 as a base to create your own layer index.
127 </para>
128
129 <section id='use-the-administration-interface'>
130 <title>Use the Administration Interface</title>
131
132 <para>
133 Access the administration interface through a
134 browser by entering the URL of your Toaster instance and
135 adding "<filename>/admin</filename>" to the end of the
136 URL.
137 </para>
138
139 <para>
140 The administration interface has a "Layer sources"
141 section that includes an "Add layer source" button.
142 Click that button and provide the required information.
143 Make sure you select "layerindex" as the layer source type.
144 </para>
145 </section>
146
147 <section id='select-the-toasterconf-json-file'>
148 <title>Select the <filename>toasterconf.json</filename> File</title>
149
150 <para>
151 If you do not want to use the Administration
152 Interface, you can edit the
153 <link linkend='toaster-json-files'><filename>toasterconf.json</filename></link>
154 file and reload it to Toaster.
155 </para>
156
157 <para>
158 When you set up Toaster in Build Mode, you are prompted to
159 select a Toaster configuration file.
160 This configuration file is used to set up the initial
161 configuration values within the Toaster database
162 including the layer sources.
163 Three versions of the configuration file exist:
164 <itemizedlist>
165 <listitem><para>
166 The first version of the file is found in the
167 <filename>conf</filename> directory of the
168 <filename>meta-yocto</filename> layer
169 (i.e.
170 <filename>meta-yocto/conf/toasterconf.json</filename>).
171 This version contains the default Yocto Project
172 configuration for Toaster.
173 You are prompted to select this file during the
174 Toaster set up process if you had cloned the
175 <filename>poky</filename> repository (i.e.
176 <filename>git://git.yoctoproject.org/poky</filename>).
177 </para></listitem>
178 <listitem><para>
179 The second version of the file is in the
180 <filename>conf</filename> directory of the
181 <filename>openembedded-core</filename> layer
182 (i.e. <filename>meta/conf/toasterconf.json</filename>).
183 This version contains the default OpenEmbedded
184 configuration for Toaster.
185 You are prompted to select this file during the
186 Toaster set up process if you had cloned the
187 <filename>openembedded-core</filename> repository
188 (i.e.
189 <filename>git://git.openembedded.org/openembedded-core</filename>).
190 </para></listitem>
191 <listitem><para>
192 The third version is a sample configuration
193 useful for when you want to set up a hosted
194 service in Build Mode.
195 You can find this version on the
196 <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>File:Toasterconf.json.txt.patch</ulink>
197 wiki page.
198 </para></listitem>
199 </itemizedlist>
200 </para>
201 </section>
202
203 <section id='edit-the-configuration-file'>
204 <title>Edit the Configuration File</title>
205
206 <para>
207 Edit the version of the
208 <filename>toasterconf.json</filename> file you
209 used to set up your Toaster instance.
210 In the file, you will find a section for layer sources
211 such as the following:
212 <literallayout class='monospaced'>
213 "layersources": [
214 {
215 "name": "Local Yocto Project",
216 "sourcetype": "local",
217 "apiurl": "../../",
218 "branches": ["HEAD", "master", "fido", "dizzy"],
219 "layers": [
220 {
221 "name": "openembedded-core",
222 "local_path": "meta",
223 "vcs_url": "remote:origin",
224 "dirpath": "meta"
225 },
226 {
227 "name": "meta-yocto",
228 "local_path": "meta-yocto",
229 "vcs_url": "remote:origin",
230 "dirpath": "meta-yocto"
231 },
232 {
233 "name": "meta-yocto-bsp",
234 "local_path": "meta-yocto-bsp",
235 "vcs_url": "remote:origin",
236 "dirpath": "meta-yocto-bsp"
237 }
238
239 ]
240 },
241 {
242 "name": "OpenEmbedded",
243 "sourcetype": "layerindex",
244 "apiurl": "http://layers.openembedded.org/layerindex/api/",
245 "branches": ["master", "fido", "dizzy"]
246 },
247 {
248 "name": "Imported layers",
249 "sourcetype": "imported",
250 "apiurl": "",
251 "branches": ["master", "fido", "dizzy", "HEAD"]
252
253 }
254 ],
255 </literallayout>
256 You should add your own layer source to this section by
257 following the same format used for the "OpenEmbedded"
258 layer source shown above.
259 </para>
260
261 <para>
262 Give your layer source a name, provide the URL of your
263 layer source API, use the source type "layerindex", and
264 indicate which branches from your layer source you want
265 to make available through Toaster.
266 For example, the OpenEmbedded layer source makes
267 available only its "master", "fido", and "dizzy"
268 branches.
269 </para>
270
271 <para>
272 The branches must match the branch you
273 set when configuring your releases.
274 For example, if you configure one release in Toaster
275 by setting its branch to "branch-one" and you configure
276 another release in Toaster by setting its branch to
277 "branch-two", the branches in your layer source should
278 be "branch-one" and "branch-two" as well.
279 Doing so creates a connection between the releases
280 and the layer information from your layer source.
281 Thus, when users create a project with a given
282 release, they will see the appropriate layers from
283 your layer source.
284 This connection ensures that only layers that are
285 compatible with the selected project release can be
286 selected for building.
287 </para>
288
289 <para>
290 Once you have added this information to the
291 <filename>toasterconf.json</filename> file, save your
292 changes.
293 </para>
294
295 <para>
296 In a terminal window, navigate to the directory that
297 contains the Toaster database, which by default is the
298 root of the Yocto Project
299 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
300 Once you are located in that directory, run the
301 "<filename>loadconf</filename>" command, which takes as
302 an argument the full path to the
303 <filename>toasterconf.json</filename> file you just edited.
304 For example, if you cloned the
305 <filename>poky</filename> repository and you edited the
306 <filename>meta-yocto/conf/toasterconf.json</filename> file,
307 you would type something like the following:
308 <literallayout class='monospaced'>
309 $ bitbake/lib/toaster/manage.py loadconf /home/scottrif/poky/meta-yocto/conf/toasterconf.json
310 </literallayout>
311 After entering this command, you need to update the
312 information from the layer index to populate the
313 Toaster database with the information from your layer
314 index.
315 To do that, you should run the
316 "<filename>lsupdates</filename>" command from the directory
317 that contains the Toaster database.
318 Here is an example:
319 <literallayout class='monospaced'>
320 $ bitbake/lib/toaster/manage.py lsupdates
321 </literallayout>
322 If Toaster can reach the API URL, you should see a message
323 telling you that Toaster is updating the layer source
324 information.
325 </para>
326
327 <para>
328 Once the information has been updated, verify the new layer
329 information is available by using the Toaster web interface.
330 To do that, visit the "All compatible layers" page inside a
331 Toaster project.
332 The layers from your layer index should be listed there.
333 </para>
334 </section>
335 </section>
336 </section>
337 </section>
338
339 <section id='toaster-releases'>
340 <title>Releases</title>
341
342 <para>
343 In the context of Toaster, the term "Release" refers to a set of
344 layers and a BitBake version the OpenEmbedded build system uses
345 to build something.
346 As shipped, Toaster is pre-configured with releases that
347 correspond to Yocto Project release branches.
348 However, you can modify, delete, and create new releases
349 according to your needs.
350 When you create a Toaster project using the web interface,
351 you are asked to choose a "Release."
352 This section provides some background information on releases.
353 </para>
354
355 <section id='toaster-releases-supported'>
356 <title>Pre-Configured Releases</title>
357
358 <para>
359 As shipped, Toaster is configured to use a specific set of
360 releases.
361 Of course, you can always configure Toaster to use any
362 release.
363 For example, you might want your project to build against a
364 specific commit of any of the "out-of-the-box" releases.
365 Or, you might want your project to build against different
366 revisions of OpenEmbedded and BitBake.
367 </para>
368
369 <para>
370 As shipped, Toaster is configured to work with the following
371 releases:
372 <itemizedlist>
373 <listitem><para><emphasis>Yocto Project 1.7 "Dizzy" or OpenEmbedded "Dizzy":</emphasis>
374 This release causes your Toaster projects to
375 build against the head of the dizzy branch at
376 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/?h=dizzy'></ulink>
377 or
378 <ulink url='http://git.openembedded.org/openembedded-core/commit/?h=dizzy'></ulink>.
379 </para></listitem>
380 <listitem><para><emphasis>Yocto Project 1.8 "Fido" or OpenEmbedded "Fido":</emphasis>
381 This release causes your Toaster projects to
382 build against the head of the fido branch at
383 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/?h=fido'></ulink>
384 or
385 <ulink url='http://git.openembedded.org/openembedded-core/commit/?h=fido'></ulink>.
386 </para></listitem>
387 <listitem><para><emphasis>Yocto Project "Master" or OpenEmbedded "Master":</emphasis>
388 This release causes your Toaster Projects to
389 build against the head of the master branch, which is
390 where active development takes place, at
391 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/'></ulink>
392 or
393 <ulink url='http://git.openembedded.org/openembedded-core/log/'></ulink>.
394 </para></listitem>
395 <listitem><para><emphasis>Local Yocto Project or Local OpenEmbedded:</emphasis>
396 This release causes your Toaster Projects to
397 build against the head of the <filename>poky</filename>
398 or <filename>openembedded-core</filename> clone you
399 have local to the machine running Toaster.
400 </para></listitem>
401 </itemizedlist>
402 </para>
403 </section>
404
405 <section id='toaster-releases-comprised-of'>
406 <title>What Makes Up a Release?</title>
407
408 <para>
409 A release consists of the following:
410 <itemizedlist>
411 <listitem><para><emphasis>Name:</emphasis>
412 The name of the release (<filename>name</filename>).
413 This release name never appears in the the Toaster
414 web interface.
415 Consequently, a user never sees the release name.
416 </para></listitem>
417 <listitem><para><emphasis>Description:</emphasis>
418 The textual description of the release
419 (<filename>description</filename>).
420 This description is what users encounter when creating
421 projects with the Toaster web interface.
422 When you configure your release, be sure to use
423 a description that sufficiently describes and is
424 understandable.
425 If Toaster has more than one release configured, the
426 release descriptions appear listed in a drop down menu
427 when a user creates a new project.
428 If Toaster has only one release configured, all
429 projects created using the web interface take that
430 release and the drop down menu does not display in the
431 Toaster web interface.
432 </para></listitem>
433 <listitem><para><emphasis>BitBake:</emphasis>
434 The Bitbake version (<filename>bitbake</filename>)
435 used to build layers set in the current release.
436 This version is described by a name, a Git URL, a
437 branch in the Git URL, and a directory path in the
438 Git repository.
439 As an example, consider the following snippet from
440 a Toaster JSON configuration file.
441 This BitBake version uses the master branch from the
442 OpenEmbedded repository:
443 <literallayout class='monospaced'>
444 "bitbake" : [
445 {
446 "name": "master",
447 "giturl": "git://git.openembedded.org/bitbake",
448 "branch": "master",
449 "dirpath": ""
450 }
451 ]
452 </literallayout>
453 Here is more detail on each of the items that comprise
454 the BitBake version:
455 <itemizedlist>
456 <listitem><para><emphasis>Name:</emphasis>
457 A string
458 (<filename>name</filename>) used to refer to
459 the version of BitBake you are using with
460 Toaster.
461 This name is never exposed through Toaster.
462 </para></listitem>
463 <listitem><para><emphasis>Git URL:</emphasis>
464 The URL <filename>giturl</filename>
465 for the BitBake Git repository cloned
466 for Toaster projects.
467 </para></listitem>
468 <listitem><para><emphasis>Branch:</emphasis>
469 The Git branch, or revision,
470 (<filename>branch</filename>) of the BitBake
471 repository used with Toaster.
472 </para></listitem>
473 <listitem><para><emphasis>Directory Path:</emphasis>
474 The sub-directory of the BitBake repository
475 (<filename>dirpath</filename>).
476 If the Git URL includes more than one
477 repository, you need to set this directory.
478 If the URL does not include more than a single
479 repository, you can set
480 <filename>dirpath</filename> to a null string
481 (i.e. "").
482 </para></listitem>
483 </itemizedlist>
484 </para></listitem>
485 <listitem><para><emphasis>Branch:</emphasis>
486 The branch for the layer source
487 (<filename>branch</filename>) used with the release.
488 For example, for the OpenEmbedded layer source, the
489 "master", "fido", and "dizzy" branches are available.
490 </para></listitem>
491 <listitem><para><emphasis>Default Layers:</emphasis>
492 The set of default layers
493 (<filename>defaultlayers</filename>) automatically
494 added to the project configuration when a project is
495 created.
496 You can download the recommended configuration
497 for this case from
498 <ulink url='&YOCTO_WIKI_URL;/wiki/File:Toasterconf.json.txt.patch'></ulink>.
499 </para></listitem>
500 <listitem><para><emphasis>Layer Source Priorities</emphasis>
501 A specification of
502 <link linkend='layer-source'>layer source</link>
503 priorities (<filename>layersourcepriority</filename>).
504 In order for Toaster to work as intended, the
505 "Imported layers" layer source should have the highest
506 priority, which means that layers manually imported by
507 users with the "Import layer" functionality will
508 always be visible and available for selection.
509 </para></listitem>
510 <listitem><para><emphasis>Help Text:</emphasis>
511 Help text (<filename>helptext</filename>) that explains
512 what the release does when selected.
513 This help text appears below the release drop-down
514 menu when you create a Toaster project.
515 The help text should assist users in making the correct
516 decision regarding the release to use for a given
517 project.
518 </para></listitem>
519 </itemizedlist>
520 </para>
521
522 <para>
523 To summarize what comprises a release, consider the following
524 example from a Toaster JSON file.
525 The configuration names the release "master" and sets it to
526 use the master branch of the
527 <filename>openembedded-core</filename> layer.
528 The BitBake version used would be defined as shown earlier
529 in the previous list:
530 <literallayout class='monospaced'>
531 "releases": [
532 {
533 "name": "master",
534 "description": "OpenEmbedded master",
535 "bitbake": "master",
536 "branch": "master",
537 "defaultlayers": [ "openembedded-core" ],
538 "layersourcepriority": { "Imported layers": 99, "Local OpenEmbedded" : 10, "OpenEmbedded" : 0 },
539 "helptext": "Toaster will run your builds using the OpenEmbedded master branch, where active development takes place. This is not a stable branch, so your builds might not work as expected."
540 }
541 ]
542 </literallayout>
543 </para>
544 </section>
545 </section>
546
547 <section id='toaster-json-files'>
548 <title>JSON Files</title>
549
550 <para>
551 If you are going to be using the Toaster in Build Mode, it must
552 be initially configured before use.
553 Configuration customizes layer source settings and Toaster defaults
554 for all users and is performed by the person responsible for
555 Toaster Configuration (i.e the Toaster Administrator).
556 The Toaster Administrator performs this configuration through the
557 admin web interface.
558 </para>
559
560 <para>
561 To make it easier to initially start Toaster, you can import a
562 pre-defined configuration file using the
563 <link linkend='toaster-command-loadconf'><filename>loadconf</filename></link>
564 command.
565 <note>
566 The configuration file is a JSON-formatted text file with
567 specific fields that Toaster recognizes.
568 It is not a data dump from the database, so it cannot be
569 loaded directly in the database.
570 </note>
571 </para>
572
573 <para>
574 By convention, the supplied configuration files are named
575 <filename>toasterconf.json</filename>.
576 The Toaster Administrator can customize the file prior to loading
577 it into Toaster.
578 In the Local Toaster Build Mode, the system startup script
579 actively looks for compatible configuration files and prompts
580 you to select a file to load if it detects that the database has
581 not been configured.
582 </para>
583
584 <section id='json-file-choices'>
585 <title>Configuration File Choices</title>
586
587 <para>
588 Three versions of the configuration file exist:
589 <itemizedlist>
590 <listitem><para>
591 The
592 <filename>meta-yocto/conf/toasterconf.json</filename>
593 in the <filename>conf</filename> directory of the
594 Yocto Project's <filename>meta-yocto</filename> layer.
595 This version contains the default Yocto Project
596 configuration for Toaster.
597 You are prompted to select this file during the Toaster
598 set up process if you cloned the
599 <filename>poky</filename> repository (i.e.
600 <filename>&YOCTO_GIT_URL;/poky</filename>).
601 </para></listitem>
602 <listitem><para>
603 The <filename>meta/conf/toasterconf.json</filename>
604 in the <filename>conf</filename> directory of the
605 OpenEmbedded's <filename>openembedded-core</filename>
606 layer.
607 This version contains the default OpenEmbedded
608 configuration for Toaster.
609 You are prompted to select this file during the Toaster
610 set up process if you had cloned the
611 <filename>openembedded-core</filename> repository (i.e.
612 <filename>git://git.openembedded.org/openembedded-core</filename>).
613 </para></listitem>
614 <listitem><para>
615 The <filename>Toasterconf.json.txt.patch</filename>
616 located on the
617 <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>File:Toasterconf.json.txt.patch</ulink>
618 wiki page.
619 This version of the file is useful as a sample
620 configuration for when you want to set up Toaster as a
621 hosted service in Build Mode.
622 </para></listitem>
623 </itemizedlist>
624 </para>
625 </section>
626
627 <section id='json-structure'>
628 <title>File Structure</title>
629
630 <para>
631 The <filename>toasterconf.json</filename> file consists of
632 easily readable areas: configuration, layer sources, BitBake,
633 default, and releases.
634 </para>
635
636 <section id='json-config-area'>
637 <title>Configuration Area</title>
638
639 <para>
640 This area of the JSON file sets which variables are exposed
641 to users through the Toaster web interface.
642 Users can easily edit these variables.
643 </para>
644
645 <para>
646 The variables you set here are displayed in the
647 "Configuration variables" page in Toaster.
648 Minimally, you should set the
649 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
650 variable, which appears to users as part of the project
651 page in Toaster.
652 </para>
653
654 <para>
655 Here is the default <filename>config</filename> area:
656 <literallayout class='monospaced'>
657 "config": {
658 "MACHINE" : "qemux86",
659 "DISTRO" : "poky",
660 "IMAGE_FSTYPES": "ext3 jffs2 tar.bz2",
661 "IMAGE_INSTALL_append": "",
662 "PACKAGE_CLASSES": "package_rpm",
663 "SDKMACHINE" : "x86_64"
664 },
665 </literallayout>
666 </para>
667 </section>
668
669 <section id='json-layersources-area'>
670 <title>Layer Sources Area</title>
671
672 <para>
673 This area of the JSON file defines the
674 <link linkend='layer-source'>layer sources</link>
675 Toaster uses.
676 Toaster reads layer information from layer sources.
677 Three types of layer sources exist that Toaster
678 recognizes: Local, LayerIndex, and Imported.
679 </para>
680
681 <para>
682 The Local layer source reads layers from Git clones
683 available on your local drive.
684 Using a local layer source enables you to easily test
685 Toaster.
686 <note>
687 If you are setting up a hosted version of Toaster,
688 it does not make sense to have a local layer source.
689 </note>
690 </para>
691
692 <para>
693 The LayerIndex layer source uses a REST API exposed by
694 instances of the Layer Index application (e.g the public
695 <ulink url='http://layers.openembedded.org/'></ulink>)
696 to read layer data.
697 </para>
698
699 <para>
700 The Imported layer source is reserved for layer data
701 manually introduced by the user or Toaster Administrator
702 through the GUI.
703 This layer source lets users import their own layers
704 and build them with Toaster.
705 You should not remove the imported layer source.
706 </para>
707
708 <para>
709 Here is the default <filename>layersources</filename> area:
710 <literallayout class='monospaced'>
711 "layersources": [
712 {
713 "name": "Local Yocto Project",
714 "sourcetype": "local",
715 "apiurl": "../../",
716 "branches": ["HEAD", "master", "fido", "dizzy"],
717 "layers": [
718 {
719 "name": "openembedded-core",
720 "local_path": "meta",
721 "vcs_url": "remote:origin",
722 "dirpath": "meta"
723 },
724 {
725 "name": "meta-yocto",
726 "local_path": "meta-yocto",
727 "vcs_url": "remote:origin",
728 "dirpath": "meta-yocto"
729 },
730 {
731 "name": "meta-yocto-bsp",
732 "local_path": "meta-yocto-bsp",
733 "vcs_url": "remote:origin",
734 "dirpath": "meta-yocto-bsp"
735 }
736
737 ]
738 },
739 {
740 "name": "OpenEmbedded",
741 "sourcetype": "layerindex",
742 "apiurl": "http://layers.openembedded.org/layerindex/api/",
743 "branches": ["master", "fido", "dizzy"]
744 },
745 {
746 "name": "Imported layers",
747 "sourcetype": "imported",
748 "apiurl": "",
749 "branches": ["master", "fido", "dizzy", "HEAD"]
750
751 }
752 ],
753 </literallayout>
754 </para>
755 </section>
756
757 <section id='json-bitbake-area'>
758 <title>BitBake Area</title>
759
760 <para>
761 This area of the JSON file defines the version of
762 BitBake Toaster uses.
763 As shipped, Toaster is configured to recognize three
764 versions of BitBake: master, dizzy, and HEAD.
765 </para>
766
767 <para>
768 Here is the default <filename>bitbake</filename> area:
769 <literallayout class='monospaced'>
770 "bitbake" : [
771 {
772 "name": "master",
773 "giturl": "remote:origin",
774 "branch": "master",
775 "dirpath": "bitbake"
776 },
777 {
778 "name": "fido",
779 "giturl": "remote:origin",
780 "branch": "fido",
781 "dirpath": "bitbake"
782 },
783 {
784 "name": "dizzy",
785 "giturl": "remote:origin",
786 "branch": "dizzy",
787 "dirpath": "bitbake"
788 },
789 {
790 "name": "HEAD",
791 "giturl": "remote:origin",
792 "branch": "HEAD",
793 "dirpath": "bitbake"
794 }
795 ],
796 </literallayout>
797 </para>
798 </section>
799
800 <section id='json-default-area'>
801 <title>Default Area</title>
802
803 <para>
804 This area of the JSON file establishes a default
805 release used by Toaster.
806 As shipped, Toaster uses the "master" release.
807 </para>
808
809 <para>
810 Here is the statement in the JSON file that establishes
811 the default release:
812 <literallayout class='monospaced'>
813 "defaultrelease": "master",
814 </literallayout>
815 </para>
816 </section>
817
818 <section id='json-releases-area'>
819 <title>Releases Area</title>
820
821 <para>
822 This area of the JSON file defines the versions of the
823 OpenEmbedded build system Toaster recognizes.
824 As shipped, Toaster is configured to work with the four
825 releases described in the
826 "<link linkend='toaster-releases-supported'>Pre-Configured Releases</link>"
827 section.
828 </para>
829
830 <para>
831 Here is the default <filename>releases</filename> area:
832 <literallayout class='monospaced'>
833 "releases": [
834 {
835 "name": "master",
836 "description": "Yocto Project master",
837 "bitbake": "master",
838 "branch": "master",
839 "defaultlayers": [ "openembedded-core", "meta-yocto", "meta-yocto-bsp"],
840 "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 },
841 "helptext": "Toaster will run your builds using the tip of the &lt;a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/\"&gt;Yocto Project master branch&lt;/a&gt;, where active development takes place. This is not a stable branch, so your builds might not work as expected."
842 },
843 {
844 "name": "fido",
845 "description": "Yocto Project 1.8 Fido",
846 "bitbake": "fido",
847 "branch": "fido",
848 "defaultlayers": [ "openembedded-core", "meta-yocto", "meta-yocto-bsp"],
849 "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 },
850 "helptext": "Toaster will run your builds with the tip of the &lt;a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=fido\"&gt;Yocto Project 1.8 \"Fido\"&lt;/a&gt; branch."
851 },
852 {
853 "name": "dizzy",
854 "description": "Yocto Project 1.7 Dizzy",
855 "bitbake": "dizzy",
856 "branch": "dizzy",
857 "defaultlayers": [ "openembedded-core", "meta-yocto", "meta-yocto-bsp"],
858 "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 },
859 "helptext": "Toaster will run your builds with the tip of the &lt;a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=dizzy\"&gt;Yocto Project 1.7 \"Dizzy\"&lt;/a&gt; branch."
860 },
861 {
862 "name": "local",
863 "description": "Local Yocto Project",
864 "bitbake": "HEAD",
865 "branch": "HEAD",
866 "defaultlayers": [ "openembedded-core", "meta-yocto", "meta-yocto-bsp"],
867 "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 },
868 "helptext": "Toaster will run your builds with the version of the Yocto Project you have cloned or downloaded to your computer."
869 }
870 ]
871 </literallayout>
872 </para>
873 </section>
874 </section>
875 </section>
876
877 <section id='toaster-useful-commands'>
878 <title>Useful Commands</title>
879
880 <para>
881 In addition to the web user interface and the scripts that start
882 and stop Toaster, command-line commands exist through the
883 <filename>manage.py</filename> management script.
884 You can find general documentation on
885 <filename>manage.py</filename> at the
886 <ulink url='https://docs.djangoproject.com/en/1.7/topics/settings/'>Django</ulink>
887 site.
888 However, several <filename>manage.py</filename> commands have been
889 created that are specific to Toaster and are used to control
890 configuration and back-end tasks.
891 You can locate these commands in the
892 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
893 (e.g. <filename>poky</filename>) at
894 <filename>bitbake/lib/manage.py</filename>.
895 This section documents those commands.
896 <note>
897 <para>
898 When using <filename>manage.py</filename> commands given
899 a default configuration, you must be sure that your
900 working directory is set to the
901 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
902 Using <filename>manage.py</filename> commands from the
903 Build Directory allows Toaster to find the
904 <filename>toaster.sqlite</filename> file, which is located
905 in the Build Directory.
906 </para>
907
908 <para>
909 For non-default database configurations, it is possible
910 that you can use <filename>manage.py</filename> commands
911 from a directory other than the Build directory.
912 To do so, the
913 <filename>toastermain/settings.py</filename> file must be
914 configured to point to the correct database backend.
915 </para>
916 </note>
917 </para>
918
919 <section id='toaster-command-buildslist'>
920 <title><filename>buildslist</filename></title>
921
922 <para>
923 The <filename>buildslist</filename> command lists all builds
924 that Toaster has recorded.
925 Access the command as follows:
926 <literallayout class='monospaced'>
927 $ bitbake/lib/toaster/manage.py buildslist
928 </literallayout>
929 The command returns a list, which includes numeric
930 identifications, of the builds that Toaster has recorded in the
931 current database.
932 </para>
933
934 <para>
935 You need to run the <filename>buildslist</filename> command
936 first to identify existing builds in the database before
937 using the
938 <link linkend='toaster-command-builddelete'><filename>builddelete</filename></link>
939 command.
940 For example, assuming default repository and build directory
941 names, the following two commands put you in the
942 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
943 and then return a list of the current builds, which would
944 be one in this case:
945 <literallayout class='monospaced'>
946 $ cd $HOME/poky/build
947 $ python ../bitbake/lib/toaster/manage.py buildslist
948 1: qemux86 poky core-image-minimal
949 </literallayout>
950 </para>
951 </section>
952
953 <section id='toaster-command-builddelete'>
954 <title><filename>builddelete</filename></title>
955
956 <para>
957 The <filename>builddelete</filename> command deletes data
958 associated with a build.
959 Access the command as follows:
960 <literallayout class='monospaced'>
961 $ bitbake/lib/toaster/manage.py builddelete <replaceable>build_id</replaceable>
962 </literallayout>
963 The command deletes all the build data for the specified
964 <replaceable>build_id</replaceable>.
965 This command is useful for removing old and unused data from
966 the database.
967 </para>
968
969 <para>
970 Prior to running the <filename>builddelete</filename>
971 command, you need to get the ID associated with builds
972 by using the
973 <link linkend='toaster-command-buildslist'><filename>buildslist</filename></link>
974 command.
975 </para>
976 </section>
977
978 <section id='toaster-command-perf'>
979 <title><filename>perf</filename></title>
980
981 <para>
982 The <filename>perf</filename> command measures Toaster
983 performance.
984 Access the command as follows:
985 <literallayout class='monospaced'>
986 $ bitbake/lib/toaster/manage.py perf
987 </literallayout>
988 The command is a sanity check that returns page loading
989 times in order to identify performance problems.
990 </para>
991 </section>
992
993 <section id='toaster-command-checksettings'>
994 <title><filename>checksettings</filename></title>
995
996 <para>
997 The <filename>checksettings</filename> command verifies
998 existing Toaster settings.
999 Access the command as follows:
1000 <literallayout class='monospaced'>
1001 $ bitbake/lib/toaster/manage.py checksettings
1002 </literallayout>
1003 In Managed Mode, Toaster uses settings that are based on the
1004 database to configure the building tasks.
1005 The <filename>checksettings</filename> command verifies that
1006 the database settings are valid in the sense that they have
1007 the minimal information needed to start a build.
1008 </para>
1009
1010 <para>
1011 In order for the <filename>checksettings</filename> command
1012 to work, the database must be correctly set up and not have
1013 existing data.
1014 To be sure the database is ready, you can run the following:
1015 <literallayout class='monospaced'>
1016 $ bitbake/lib/toaster/mana​ge.py syncdb
1017 $ bitbake/lib/toaster/mana​ge.py migrate orm
1018 $ bitbake/lib/toaster/mana​ge.py migrate bldcontrol
1019 </literallayout>
1020 After running these commands, you can run the
1021 <filename>checksettings</filename> command.
1022 </para>
1023 </section>
1024
1025 <section id='toaster-command-loadconf'>
1026 <title><filename>loadconf</filename></title>
1027
1028 <para>
1029 The <filename>loadconf</filename> command loads a Toaster
1030 configuration file (JSON file).
1031 You must run this on a new database that does not have any
1032 data.
1033 Running this command on an existing database that has data
1034 results in errors.
1035 Access the command as follows:
1036 <literallayout class='monospaced'>
1037 $ bitbake/lib/toaster/manage.py loadconf <replaceable>filepath</replaceable>
1038 </literallayout>
1039 The <filename>loadconf</filename> command configures a database
1040 based on the supplied <filename>toasterconf.json</filename>
1041 file.
1042 For information on the <filename>toasterconf.json</filename>,
1043 see the
1044 "<link linkend='toaster-json-files'>JSON Files</link>"
1045 section.
1046 </para>
1047 </section>
1048
1049 <section id='toaster-command-runbuilds'>
1050 <title><filename>runbuilds</filename></title>
1051
1052 <para>
1053 The <filename>runbuilds</filename> command launched
1054 scheduled builds.
1055 Access the command as follows:
1056 <literallayout class='monospaced'>
1057 $ bitbake/lib/toaster/manage.py runbuilds
1058 </literallayout>
1059 The <filename>runbuilds</filename> command checks if
1060 scheduled builds exist in the database and then launches them
1061 per schedule.
1062 The command returns after the builds start but before they
1063 complete.
1064 The "toasterui" build recorded updates the database when the
1065 builds complete.
1066 </para>
1067 </section>
1068 </section>
1069</chapter>