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