summaryrefslogtreecommitdiffstats
path: root/documentation/toaster-manual/toaster-manual-reference.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/toaster-manual/toaster-manual-reference.xml')
-rw-r--r--documentation/toaster-manual/toaster-manual-reference.xml837
1 files changed, 0 insertions, 837 deletions
diff --git a/documentation/toaster-manual/toaster-manual-reference.xml b/documentation/toaster-manual/toaster-manual-reference.xml
deleted file mode 100644
index ae267f4184..0000000000
--- a/documentation/toaster-manual/toaster-manual-reference.xml
+++ /dev/null
@@ -1,837 +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-reference'>
7
8<title>Concepts and Reference</title>
9
10 <para>
11 In order to configure and use Toaster, you should understand some
12 concepts and have some basic command reference material available.
13 This final chapter provides conceptual information on layer sources,
14 releases, and JSON configuration files.
15 Also provided is a quick look at some useful
16 <filename>manage.py</filename> commands that are Toaster-specific.
17 Information on <filename>manage.py</filename> commands does exist
18 across the Web and the information in this manual by no means
19 attempts to provide a command comprehensive reference.
20 </para>
21
22 <section id='layer-source'>
23 <title>Layer Source</title>
24
25 <para>
26 In general, a "layer source" is a source of information about
27 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 Layer 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_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
97 section in the Yocto Project Overview and Concepts Manual.
98 For information on how to create layers, see the
99 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
100 section in the Yocto Project Development Tasks Manual.
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 As an example, if you are running Toaster locally, use
138 the following URL:
139 <literallayout class='monospaced'>
140 http://127.0.0.1:8000/admin
141 </literallayout>
142 </para>
143
144 <para>
145 The administration interface has a "Layer sources"
146 section that includes an "Add layer source" button.
147 Click that button and provide the required information.
148 Make sure you select "layerindex" as the layer source type.
149 </para>
150 </section>
151
152 <section id='use-the-fixture-feature'>
153 <title>Use the Fixture Feature</title>
154
155 <para>
156 The Django fixture feature overrides the default layer
157 server when you use it to specify a custom URL. To use
158 the fixture feature, create (or edit) the file
159 <filename>bitbake/lib/toaster.orm/fixtures/custom.xml</filename>,
160 and then set the following Toaster setting to your
161 custom URL:
162 <literallayout class='monospaced'>
163 &lt;?xml version="1.0" ?&gt;
164 &lt;django-objects version="1.0"&gt;
165 &lt;object model="orm.toastersetting" pk="100"&gt;
166 &lt;field name="name" type="CharField"&gt;CUSTOM_LAYERINDEX_SERVER&lt;/field&gt;
167 &lt;field name="value" type="CharField"&gt;https://layers.my_organization.org/layerindex/branch/master/layers/&lt;/field&gt;
168 &lt;/object&gt;
169 &lt;django-objects&gt;
170 </literallayout>
171 When you start Toaster for the first time, or if you
172 delete the file <filename>toaster.sqlite</filename> and restart,
173 the database will populate cleanly from this layer index server.
174 </para>
175
176 <para>
177 Once the information has been updated, verify the new layer
178 information is available by using the Toaster web interface.
179 To do that, visit the "All compatible layers" page inside a
180 Toaster project. The layers from your layer source should be
181 listed there.
182 </para>
183
184 <para>
185 If you change the information in your layer index server,
186 refresh the Toaster database by running the following command:
187 <literallayout class='monospaced'>
188 $ bitbake/lib/toaster/manage.py lsupdates
189 </literallayout>
190 If Toaster can reach the API URL, you should see a message
191 telling you that Toaster is updating the layer source information.
192 </para>
193 </section>
194 </section>
195 </section>
196 </section>
197
198 <section id='toaster-releases'>
199 <title>Releases</title>
200
201 <para>
202 When you create a Toaster project using the web interface,
203 you are asked to choose a "Release."
204 In the context of Toaster, the term "Release" refers to a set of
205 layers and a BitBake version the OpenEmbedded build system uses
206 to build something.
207 As shipped, Toaster is pre-configured with releases that
208 correspond to Yocto Project release branches.
209 However, you can modify, delete, and create new releases
210 according to your needs.
211 This section provides some background information on releases.
212 </para>
213
214 <section id='toaster-releases-supported'>
215 <title>Pre-Configured Releases</title>
216
217 <para>
218 As shipped, Toaster is configured to use a specific set of
219 releases.
220 Of course, you can always configure Toaster to use any
221 release.
222 For example, you might want your project to build against a
223 specific commit of any of the "out-of-the-box" releases.
224 Or, you might want your project to build against different
225 revisions of OpenEmbedded and BitBake.
226 </para>
227
228 <para>
229 As shipped, Toaster is configured to work with the following
230 releases:
231 <itemizedlist>
232 <listitem><para><emphasis>
233 Yocto Project &DISTRO; "&DISTRO_NAME;" or OpenEmbedded "&DISTRO_NAME;":</emphasis>
234 This release causes your Toaster projects to build
235 against the head of the &DISTRO_NAME_NO_CAP; branch at
236 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/?h=rocko'></ulink>
237 or <ulink url='http://git.openembedded.org/openembedded-core/commit/?h=rocko'></ulink>.
238 </para></listitem>
239 <listitem><para><emphasis>Yocto Project "Master" or OpenEmbedded "Master":</emphasis>
240 This release causes your Toaster Projects to
241 build against the head of the master branch, which is
242 where active development takes place, at
243 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/'></ulink>
244 or
245 <ulink url='http://git.openembedded.org/openembedded-core/log/'></ulink>.
246 </para></listitem>
247 <listitem><para><emphasis>Local Yocto Project or Local OpenEmbedded:</emphasis>
248 This release causes your Toaster Projects to
249 build against the head of the <filename>poky</filename>
250 or <filename>openembedded-core</filename> clone you
251 have local to the machine running Toaster.
252 </para></listitem>
253 </itemizedlist>
254 </para>
255 </section>
256 </section>
257
258 <section id='configuring-toaster'>
259 <title>Configuring Toaster</title>
260
261 <para>
262 In order to use Toaster, you must configure the database with the
263 default content. The following subsections describe various aspects
264 of Toaster configuration.
265 </para>
266
267 <section id='configuring-the-workflow'>
268 <title>Configuring the Workflow</title>
269
270 <para>
271 The
272 <filename>bldcontrol/management/commands/checksettings.py</filename>
273 file controls workflow configuration.
274 The following steps outline the process to initially populate
275 this database.
276 <orderedlist>
277 <listitem><para>
278 The default project settings are set from
279 <filename>orm/fixtures/settings.xml</filename>.
280 </para></listitem>
281 <listitem><para>
282 The default project distro and layers are added
283 from <filename>orm/fixtures/poky.xml</filename> if poky
284 is installed.
285 If poky is not installed, they are added
286 from <filename>orm/fixtures/oe-core.xml</filename>.
287 </para></listitem>
288 <listitem><para>
289 If the <filename>orm/fixtures/custom.xml</filename> file
290 exists, then its values are added.
291 </para></listitem>
292 <listitem><para>
293 The layer index is then scanned and added to the database.
294 </para></listitem>
295 </orderedlist>
296 Once these steps complete, Toaster is set up and ready to use.
297 </para>
298 </section>
299
300 <section id='customizing-pre-set-data'>
301 <title>Customizing Pre-Set Data</title>
302
303 <para>
304 The pre-set data for Toaster is easily customizable. You can
305 create the <filename>orm/fixtures/custom.xml</filename> file
306 to customize the values that go into to the database.
307 Customization is additive,
308 and can either extend or completely replace the existing values.
309 </para>
310
311 <para>
312 You use the <filename>orm/fixtures/custom.xml</filename> file
313 to change the default project settings for the machine, distro,
314 file images, and layers.
315 When creating a new project, you can use the file to define
316 the offered alternate project release selections.
317 For example, you can add one or more additional selections that
318 present custom layer sets or distros, and any other local or proprietary
319 content.
320 </para>
321
322 <para>
323 Additionally, you can completely disable the content from the
324 <filename>oe-core.xml</filename> and <filename>poky.xml</filename>
325 files by defining the section shown below in the
326 <filename>settings.xml</filename> file.
327 For example, this option is particularly useful if your custom
328 configuration defines fewer releases or layers than the default
329 fixture files.
330 </para>
331
332 <para>
333 The following example sets "name" to "CUSTOM_XML_ONLY" and its value
334 to "True".
335 <literallayout class='monospaced'>
336 &lt;object model="orm.toastersetting" pk="99"&gt;
337 &lt;field type="CharField" name="name"&gt;CUSTOM_XML_ONLY&lt;/field&gt;
338 &lt;field type="CharField" name="value"&gt;True&lt;/field&gt;
339 &lt;/object&gt;
340 </literallayout>
341 </para>
342 </section>
343
344 <section id='understanding-fixture-file-format'>
345 <title>Understanding Fixture File Format</title>
346
347 <para>
348 The following is an overview of the file format used by the
349 <filename>oe-core.xml</filename>, <filename>poky.xml</filename>,
350 and <filename>custom.xml</filename> files.
351 </para>
352
353 <para>
354 The following subsections describe each of the sections in the
355 fixture files, and outline an example section of the XML code.
356 you can use to help understand this information and create a local
357 <filename>custom.xml</filename> file.
358 </para>
359
360 <section id='defining-the-default-distro-and-other-values'>
361 <title>Defining the Default Distro and Other Values</title>
362
363 <para>
364 This section defines the default distro value for new projects.
365 By default, it reserves the first Toaster Setting record "1".
366 The following demonstrates how to set the project default value
367 for
368 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>:
369 <literallayout class='monospaced'>
370 &lt;!-- Set the project default value for DISTRO --&gt;
371 &lt;object model="orm.toastersetting" pk="1"&gt;
372 &lt;field type="CharField" name="name"&gt;DEFCONF_DISTRO&lt;/field&gt;
373 &lt;field type="CharField" name="value"&gt;poky&lt;/field&gt;
374 &lt;/object&gt;
375 </literallayout>
376 You can override other default project values by adding
377 additional Toaster Setting sections such as any of the
378 settings coming from the <filename>settings.xml</filename>
379 file.
380 Also, you can add custom values that are included in the
381 BitBake environment.
382 The "pk" values must be unique.
383 By convention, values that set default project values have a
384 "DEFCONF" prefix.
385 </para>
386 </section>
387
388 <section id='defining-bitbake-version'>
389 <title>Defining BitBake Version</title>
390
391 <para>
392 The following defines which version of BitBake is used
393 for the following release selection:
394 <literallayout class='monospaced'>
395 &lt;!-- Bitbake versions which correspond to the metadata release --&gt;
396 &lt;object model="orm.bitbakeversion" pk="1"&gt;
397 &lt;field type="CharField" name="name"&gt;rocko&lt;/field&gt;
398 &lt;field type="CharField" name="giturl"&gt;git://git.yoctoproject.org/poky&lt;/field&gt;
399 &lt;field type="CharField" name="branch"&gt;rocko&lt;/field&gt;
400 &lt;field type="CharField" name="dirpath"&gt;bitbake&lt;/field&gt;
401 &lt;/object&gt;
402 </literallayout>
403 </para>
404 </section>
405
406 <section id='defining-releases'>
407 <title>Defining Release</title>
408
409 <para>
410 The following defines the releases when you create a new
411 project.
412 <literallayout class='monospaced'>
413 &lt;!-- Releases available --&gt;
414 &lt;object model="orm.release" pk="1"&gt;
415 &lt;field type="CharField" name="name"&gt;rocko&lt;/field&gt;
416 &lt;field type="CharField" name="description"&gt;Yocto Project 2.4 "Rocko"&lt;/field&gt;
417 &lt;field rel="ManyToOneRel" to="orm.bitbakeversion" name="bitbake_version"&gt;1&lt;/field&gt;
418 &lt;field type="CharField" name="branch_name"&gt;rocko&lt;/field&gt;
419 &lt;field type="TextField" name="helptext"&gt;Toaster will run your builds using the tip of the &lt;a href="http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=rocko"&gt;Yocto Project Rocko branch&lt;/a&gt;.&lt;/field&gt;
420 &lt;/object&gt;
421 </literallayout>
422 The "pk" value must match the above respective BitBake
423 version record.
424 </para>
425 </section>
426
427 <section id='defining-the-release-default-layer-names'>
428 <title>Defining the Release Default Layer Names</title>
429
430 <para>
431 The following defines the default layers for each release:
432 <literallayout class='monospaced'>
433 &lt;!-- Default project layers for each release --&gt;
434 &lt;object model="orm.releasedefaultlayer" pk="1"&gt;
435 &lt;field rel="ManyToOneRel" to="orm.release" name="release"&gt;1&lt;/field&gt;
436 &lt;field type="CharField" name="layer_name"&gt;openembedded-core&lt;/field&gt;
437 &lt;/object&gt;
438 </literallayout>
439 The 'pk' values in the example above should start at "1" and increment
440 uniquely.
441 You can use the same layer name in multiple releases.
442 </para>
443 </section>
444
445 <section id='defining-layer-definitions'>
446 <title>Defining Layer Definitions</title>
447
448 <para>
449 Layer definitions are the most complex.
450 The following defines each of the layers, and then defines the exact layer
451 version of the layer used for each respective release.
452 You must have one <filename>orm.layer</filename>
453 entry for each layer.
454 Then, with each entry you need a set of
455 <filename>orm.layer_version</filename> entries that connects
456 the layer with each release that includes the layer.
457 In general all releases include the layer.
458 <literallayout class='monospaced'>
459 &lt;object model="orm.layer" pk="1"&gt;
460 &lt;field type="CharField" name="name"&gt;openembedded-core&lt;/field&gt;
461 &lt;field type="CharField" name="layer_index_url"&gt;&lt;/field&gt;
462 &lt;field type="CharField" name="vcs_url"&gt;git://git.yoctoproject.org/poky&lt;/field&gt;
463 &lt;field type="CharField" name="vcs_web_url"&gt;http://git.yoctoproject.org/cgit/cgit.cgi/poky&lt;/field&gt;
464 &lt;field type="CharField" name="vcs_web_tree_base_url"&gt;http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%&lt;/field&gt;
465 &lt;field type="CharField" name="vcs_web_file_base_url"&gt;http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%&lt;/field&gt;
466 &lt;/object&gt;
467 &lt;object model="orm.layer_version" pk="1"&gt;
468 &lt;field rel="ManyToOneRel" to="orm.layer" name="layer"&gt;1&lt;/field&gt;
469 &lt;field type="IntegerField" name="layer_source"&gt;0&lt;/field&gt;
470 &lt;field rel="ManyToOneRel" to="orm.release" name="release"&gt;1&lt;/field&gt;
471 &lt;field type="CharField" name="branch"&gt;rocko&lt;/field&gt;
472 &lt;field type="CharField" name="dirpath"&gt;meta&lt;/field&gt;
473 &lt;/object&gt;
474 &lt;object model="orm.layer_version" pk="2"&gt;
475 &lt;field rel="ManyToOneRel" to="orm.layer" name="layer"&gt;1&lt;/field&gt;
476 &lt;field type="IntegerField" name="layer_source"&gt;0&lt;/field&gt;
477 &lt;field rel="ManyToOneRel" to="orm.release" name="release"&gt;2&lt;/field&gt;
478 &lt;field type="CharField" name="branch"&gt;HEAD&lt;/field&gt;
479 &lt;field type="CharField" name="commit"&gt;HEAD&lt;/field&gt;
480 &lt;field type="CharField" name="dirpath"&gt;meta&lt;/field&gt;
481 &lt;/object&gt;
482 &lt;object model="orm.layer_version" pk="3"&gt;
483 &lt;field rel="ManyToOneRel" to="orm.layer" name="layer"&gt;1&lt;/field&gt;
484 &lt;field type="IntegerField" name="layer_source"&gt;0&lt;/field&gt;
485 &lt;field rel="ManyToOneRel" to="orm.release" name="release"&gt;3&lt;/field&gt;
486
487 &lt;field type="CharField" name="branch"&gt;master&lt;/field&gt;
488 &lt;field type="CharField" name="dirpath"&gt;meta&lt;/field&gt;
489 &lt;/object&gt;
490 </literallayout>
491 The layer "pk" values above must be unique, and typically start at "1".
492 The layer version "pk" values must also be unique across all layers,
493 and typically start at "1".
494 </para>
495 </section>
496 </section>
497 </section>
498
499 <section id='remote-toaster-monitoring'>
500 <title>Remote Toaster Monitoring</title>
501
502 <para>
503 Toaster has an API that allows remote management applications to
504 directly query the state of the Toaster server and its builds
505 in a machine-to-machine manner.
506 This API uses the
507 <ulink url='http://en.wikipedia.org/wiki/Representational_state_transfer'>REST</ulink>
508 interface and the transfer of JSON files.
509 For example, you might
510 monitor a build inside a container through well supported
511 known HTTP ports in order to easily access a Toaster server
512 inside the container.
513 In this example, when you use this direct JSON API, you avoid
514 having web page parsing against the display the user sees.
515 </para>
516
517 <section id='checking-health'>
518 <title>Checking Health</title>
519
520 <para>
521 Before you use remote Toaster monitoring, you should do
522 a health check.
523 To do this, ping the Toaster server using the following call
524 to see if it is still alive:
525 <literallayout class='monospaced'>
526 http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/health
527 </literallayout>
528 Be sure to provide values for <replaceable>host</replaceable>
529 and <replaceable>port</replaceable>.
530 If the server is alive, you will get the response HTML:
531 <literallayout class='monospaced'>
532 &lt;!DOCTYPE html&gt;
533 &lt;html lang="en"&gt;
534 &lt;head&gt;&lt;title&gt;Toaster Health&lt;/title&gt;&lt;/head&gt;
535 &lt;body&gt;Ok&lt;/body&gt;
536 &lt;/html&gt;
537 </literallayout>
538 </para>
539 </section>
540
541 <section id='determining-status-of-builds-in-progress'>
542 <title>Determining Status of Builds in Progress</title>
543
544 <para>
545 Sometimes it is useful to determine the status of a build
546 in progress.
547 To get the status of pending builds, use the following call:
548 <literallayout class='monospaced'>
549 http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/toastergui/api/building
550 </literallayout>
551 Be sure to provide values for <replaceable>host</replaceable>
552 and <replaceable>port</replaceable>.
553 The output is a JSON file that itemizes all builds in
554 progress.
555 This file includes the time in seconds since each
556 respective build started as well as the progress of the
557 cloning, parsing, and task execution.
558 The following is sample output for a build in progress:
559 <literallayout class='monospaced'>
560 {"count": 1,
561 "building": [
562 {"machine": "beaglebone",
563 "seconds": "463.869",
564 "task": "927:2384",
565 "distro": "poky",
566 "clone": "1:1",
567 "id": 2,
568 "start": "2017-09-22T09:31:44.887Z",
569 "name": "20170922093200",
570 "parse": "818:818",
571 "project": "my_rocko",
572 "target": "core-image-minimal"
573 }]
574 }
575 </literallayout>
576 The JSON data for this query is returned in a single line.
577 In the previous example the line has been artificially split for readability.
578 </para>
579 </section>
580
581 <section id='checking-status-of-builds-completed'>
582 <title>Checking Status of Builds Completed</title>
583
584 <para>
585 Once a build is completed, you get the status when you use
586 the following call:
587 <literallayout class='monospaced'>
588 http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/toastergui/api/builds
589 </literallayout>
590 Be sure to provide values for <replaceable>host</replaceable>
591 and <replaceable>port</replaceable>.
592 The output is a JSON file that itemizes all complete builds,
593 and includes build summary information.
594 The following is sample output for a completed build:
595 <literallayout class='monospaced'>
596 {"count": 1,
597 "builds": [
598 {"distro": "poky",
599 "errors": 0,
600 "machine":
601 "beaglebone",
602 "project": "my_rocko",
603 "stop": "2017-09-22T09:26:36.017Z",
604 "target": "quilt-native",
605 "seconds": "78.193",
606 "outcome": "Succeeded",
607 "id": 1,
608 "start": "2017-09-22T09:25:17.824Z",
609 "warnings": 1,
610 "name": "20170922092618"
611 }]
612 }
613 </literallayout>
614 The JSON data for this query is returned in a single line.
615 In the previous example the line has been artificially split for readability.
616 </para>
617 </section>
618
619 <section id='determining-status-of-a-specific-build'>
620 <title>Determining Status of a Specific Build</title>
621
622 <para>
623 Sometimes it is useful to determine the status of a specific
624 build.
625 To get the status of a specific build, use the following
626 call:
627 <literallayout class='monospaced'>
628 http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/toastergui/api/build/<replaceable>ID</replaceable>
629 </literallayout>
630 Be sure to provide values for <replaceable>host</replaceable>,
631 <replaceable>port</replaceable>, and <replaceable>ID</replaceable>.
632 You can find the value for <replaceable>ID</replaceable> from the
633 Builds Completed query. See the
634 "<link linkend='checking-status-of-builds-completed'>Checking Status of Builds Completed</link>"
635 section for more information.
636 </para>
637
638 <para>
639 The output is a JSON file that itemizes the specific build
640 and includes build summary information.
641 The following is sample output for a specific build:
642 <literallayout class='monospaced'>
643 {"build":
644 {"distro": "poky",
645 "errors": 0,
646 "machine": "beaglebone",
647 "project": "my_rocko",
648 "stop": "2017-09-22T09:26:36.017Z",
649 "target": "quilt-native",
650 "seconds": "78.193",
651 "outcome": "Succeeded",
652 "id": 1,
653 "start": "2017-09-22T09:25:17.824Z",
654 "warnings": 1,
655 "name": "20170922092618",
656 "cooker_log": "/opt/user/poky/build-toaster-2/tmp/log/cooker/beaglebone/build_20170922_022607.991.log"
657 }
658 }
659 </literallayout>
660 The JSON data for this query is returned in a single line.
661 In the previous example the line has been artificially split for readability.
662 </para>
663 </section>
664 </section>
665
666 <section id='toaster-useful-commands'>
667 <title>Useful Commands</title>
668
669 <para>
670 In addition to the web user interface and the scripts that start
671 and stop Toaster, command-line commands exist through the
672 <filename>manage.py</filename> management script.
673 You can find general documentation on
674 <filename>manage.py</filename> at the
675 <ulink url='https://docs.djangoproject.com/en/1.7/topics/settings/'>Django</ulink>
676 site.
677 However, several <filename>manage.py</filename> commands have been
678 created that are specific to Toaster and are used to control
679 configuration and back-end tasks.
680 You can locate these commands in the
681 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
682 (e.g. <filename>poky</filename>) at
683 <filename>bitbake/lib/manage.py</filename>.
684 This section documents those commands.
685 <note><title>Notes</title>
686 <itemizedlist>
687 <listitem><para>
688 When using <filename>manage.py</filename> commands given
689 a default configuration, you must be sure that your
690 working directory is set to the
691 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
692 Using <filename>manage.py</filename> commands from the
693 Build Directory allows Toaster to find the
694 <filename>toaster.sqlite</filename> file, which is located
695 in the Build Directory.
696 </para></listitem>
697 <listitem><para>
698 For non-default database configurations, it is possible
699 that you can use <filename>manage.py</filename> commands
700 from a directory other than the Build Directory.
701 To do so, the
702 <filename>toastermain/settings.py</filename> file must be
703 configured to point to the correct database backend.
704 </para></listitem>
705 </itemizedlist>
706 </note>
707 </para>
708
709 <section id='toaster-command-buildslist'>
710 <title><filename>buildslist</filename></title>
711
712 <para>
713 The <filename>buildslist</filename> command lists all builds
714 that Toaster has recorded.
715 Access the command as follows:
716 <literallayout class='monospaced'>
717 $ bitbake/lib/toaster/manage.py buildslist
718 </literallayout>
719 The command returns a list, which includes numeric
720 identifications, of the builds that Toaster has recorded in the
721 current database.
722 </para>
723
724 <para>
725 You need to run the <filename>buildslist</filename> command
726 first to identify existing builds in the database before
727 using the
728 <link linkend='toaster-command-builddelete'><filename>builddelete</filename></link>
729 command.
730 Here is an example that assumes default repository and build
731 directory names:
732 <literallayout class='monospaced'>
733 $ cd ~/poky/build
734 $ python ../bitbake/lib/toaster/manage.py buildslist
735 </literallayout>
736 If your Toaster database had only one build, the above
737 <filename>buildslist</filename> command would return something
738 like the following:
739 <literallayout class='monospaced'>
740 1: qemux86 poky core-image-minimal
741 </literallayout>
742 </para>
743 </section>
744
745 <section id='toaster-command-builddelete'>
746 <title><filename>builddelete</filename></title>
747
748 <para>
749 The <filename>builddelete</filename> command deletes data
750 associated with a build.
751 Access the command as follows:
752 <literallayout class='monospaced'>
753 $ bitbake/lib/toaster/manage.py builddelete <replaceable>build_id</replaceable>
754 </literallayout>
755 The command deletes all the build data for the specified
756 <replaceable>build_id</replaceable>.
757 This command is useful for removing old and unused data from
758 the database.
759 </para>
760
761 <para>
762 Prior to running the <filename>builddelete</filename>
763 command, you need to get the ID associated with builds
764 by using the
765 <link linkend='toaster-command-buildslist'><filename>buildslist</filename></link>
766 command.
767 </para>
768 </section>
769
770 <section id='toaster-command-perf'>
771 <title><filename>perf</filename></title>
772
773 <para>
774 The <filename>perf</filename> command measures Toaster
775 performance.
776 Access the command as follows:
777 <literallayout class='monospaced'>
778 $ bitbake/lib/toaster/manage.py perf
779 </literallayout>
780 The command is a sanity check that returns page loading
781 times in order to identify performance problems.
782 </para>
783 </section>
784
785 <section id='toaster-command-checksettings'>
786 <title><filename>checksettings</filename></title>
787
788 <para>
789 The <filename>checksettings</filename> command verifies
790 existing Toaster settings.
791 Access the command as follows:
792 <literallayout class='monospaced'>
793 $ bitbake/lib/toaster/manage.py checksettings
794 </literallayout>
795 Toaster uses settings that are based on the
796 database to configure the building tasks.
797 The <filename>checksettings</filename> command verifies that
798 the database settings are valid in the sense that they have
799 the minimal information needed to start a build.
800 </para>
801
802 <para>
803 In order for the <filename>checksettings</filename> command
804 to work, the database must be correctly set up and not have
805 existing data.
806 To be sure the database is ready, you can run the following:
807 <literallayout class='monospaced'>
808 $ bitbake/lib/toaster/mana​ge.py syncdb
809 $ bitbake/lib/toaster/mana​ge.py migrate orm
810 $ bitbake/lib/toaster/mana​ge.py migrate bldcontrol
811 </literallayout>
812 After running these commands, you can run the
813 <filename>checksettings</filename> command.
814 </para>
815 </section>
816
817 <section id='toaster-command-runbuilds'>
818 <title><filename>runbuilds</filename></title>
819
820 <para>
821 The <filename>runbuilds</filename> command launches
822 scheduled builds.
823 Access the command as follows:
824 <literallayout class='monospaced'>
825 $ bitbake/lib/toaster/manage.py runbuilds
826 </literallayout>
827 The <filename>runbuilds</filename> command checks if
828 scheduled builds exist in the database and then launches them
829 per schedule.
830 The command returns after the builds start but before they
831 complete.
832 The Toaster Logging Interface records and updates the database
833 when the builds complete.
834 </para>
835 </section>
836 </section>
837</chapter>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-12 06:32:52 +0000