summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorTim Orling <timothy.t.orling@linux.intel.com>2020-09-16 13:13:37 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-09-17 10:09:35 +0100
commitb199ff072e7d59255df4b414947f43a522c166e2 (patch)
tree80298d44138bf67fce3d00749f0dbfe136f813e6
parentf8b4bbda0316d2f1b276cb2ed2cf25422c418ac1 (diff)
downloadpoky-b199ff072e7d59255df4b414947f43a522c166e2.tar.gz
sphinx: toaster-manual: fix vars, links, code blocks
Also update Django links to 2.2 LTS release (from 1.11) Replace most references to 'rocko' with variable (From yocto-docs rev: ddf1e119db93fc3f8b141a04f6d0009f933b1006) Signed-off-by: Tim Orling <timothy.t.orling@linux.intel.com> Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/toaster-manual/toaster-manual-intro.rst8
-rw-r--r--documentation/toaster-manual/toaster-manual-reference.rst423
-rw-r--r--documentation/toaster-manual/toaster-manual-setup-and-use.rst396
-rw-r--r--documentation/toaster-manual/toaster-manual-start.rst27
4 files changed, 567 insertions, 287 deletions
diff --git a/documentation/toaster-manual/toaster-manual-intro.rst b/documentation/toaster-manual/toaster-manual-intro.rst
index cc972f7c73..0b7cd41c8f 100644
--- a/documentation/toaster-manual/toaster-manual-intro.rst
+++ b/documentation/toaster-manual/toaster-manual-intro.rst
@@ -26,9 +26,9 @@ extensive information about the build process.
26 Yocto Project releases 1.8 and beyond. With the Toaster web 26 Yocto Project releases 1.8 and beyond. With the Toaster web
27 interface, you can: 27 interface, you can:
28 28
29 - Browse layers listed in the various `layer 29 - Browse layers listed in the various
30 sources <#layer-source>`__ that are available in your project 30 :ref:`layer sources <toaster-manual/toaster-manual-reference:layer source>`
31 (e.g. the OpenEmbedded Layer Index at 31 that are available in your project (e.g. the OpenEmbedded Layer Index at
32 http://layers.openembedded.org/layerindex/). 32 http://layers.openembedded.org/layerindex/).
33 33
34 - Browse images, recipes, and machines provided by those layers. 34 - Browse images, recipes, and machines provided by those layers.
@@ -78,7 +78,7 @@ extensive information about the build process.
78 - See performance information such as build time, task time, CPU 78 - See performance information such as build time, task time, CPU
79 usage, and disk I/O. 79 usage, and disk I/O.
80 80
81For an overview of Toaster shipped with the Yocto Project DISTRO 81For an overview of Toaster shipped with the Yocto Project &DISTRO;
82Release, see the "`Toaster - Yocto Project 82Release, see the "`Toaster - Yocto Project
832.2 <https://youtu.be/BlXdOYLgPxA>`__" video. 832.2 <https://youtu.be/BlXdOYLgPxA>`__" video.
84 84
diff --git a/documentation/toaster-manual/toaster-manual-reference.rst b/documentation/toaster-manual/toaster-manual-reference.rst
index a628c78cc2..e95536e052 100644
--- a/documentation/toaster-manual/toaster-manual-reference.rst
+++ b/documentation/toaster-manual/toaster-manual-reference.rst
@@ -67,11 +67,10 @@ familiar with where they reside. You will need that information when you
67set up the code for the web application that "hooks" into your set of 67set up the code for the web application that "hooks" into your set of
68layers. 68layers.
69 69
70For general information on layers, see the "`The Yocto Project Layer 70For general information on layers, see the
71Model <&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model>`__" section in 71":ref:`overview-manual/overview-manual-yp-intro:the yocto project layer model`"
72the Yocto Project Overview and Concepts Manual. For information on how 72section in the Yocto Project Overview and Concepts Manual. For information on how
73to create layers, see the "`Understanding and Creating 73to create layers, see the ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`"
74Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__"
75section in the Yocto Project Development Tasks Manual. 74section in the Yocto Project Development Tasks Manual.
76 75
77.. _configuring-toaster-to-hook-into-your-layer-source: 76.. _configuring-toaster-to-hook-into-your-layer-source:
@@ -98,7 +97,9 @@ Use the Administration Interface
98Access the administration interface through a browser by entering the 97Access the administration interface through a browser by entering the
99URL of your Toaster instance and adding "``/admin``" to the end of the 98URL of your Toaster instance and adding "``/admin``" to the end of the
100URL. As an example, if you are running Toaster locally, use the 99URL. As an example, if you are running Toaster locally, use the
101following URL: http://127.0.0.1:8000/admin 100following URL::
101
102 http://127.0.0.1:8000/admin
102 103
103The administration interface has a "Layer sources" section that includes 104The administration interface has a "Layer sources" section that includes
104an "Add layer source" button. Click that button and provide the required 105an "Add layer source" button. Click that button and provide the required
@@ -110,12 +111,19 @@ Use the Fixture Feature
110The Django fixture feature overrides the default layer server when you 111The Django fixture feature overrides the default layer server when you
111use it to specify a custom URL. To use the fixture feature, create (or 112use it to specify a custom URL. To use the fixture feature, create (or
112edit) the file ``bitbake/lib/toaster.orm/fixtures/custom.xml``, and then 113edit) the file ``bitbake/lib/toaster.orm/fixtures/custom.xml``, and then
113set the following Toaster setting to your custom URL: <?xml 114set the following Toaster setting to your custom URL:
114version="1.0" ?> <django-objects version="1.0"> <object 115
115model="orm.toastersetting" pk="100"> <field name="name" 116.. code-block:: xml
116type="CharField">CUSTOM_LAYERINDEX_SERVER</field> <field name="value" 117
117type="CharField">https://layers.my_organization.org/layerindex/branch/master/layers/</field> 118 <?xml version="1.0" ?>
118</object> <django-objects> When you start Toaster for the first time, or 119 <django-objects version="1.0">
120 <object model="orm.toastersetting" pk="100">
121 <field name="name" type="CharField">CUSTOM_LAYERINDEX_SERVER</field>
122 <field name="value" type="CharField">https://layers.my_organization.org/layerindex/branch/master/layers/</field>
123 </object>
124 <django-objects>
125
126When you start Toaster for the first time, or
119if you delete the file ``toaster.sqlite`` and restart, the database will 127if you delete the file ``toaster.sqlite`` and restart, the database will
120populate cleanly from this layer index server. 128populate cleanly from this layer index server.
121 129
@@ -125,10 +133,15 @@ is available by using the Toaster web interface. To do that, visit the
125your layer source should be listed there. 133your layer source should be listed there.
126 134
127If you change the information in your layer index server, refresh the 135If you change the information in your layer index server, refresh the
128Toaster database by running the following command: $ 136Toaster database by running the following command:
129bitbake/lib/toaster/manage.py lsupdates If Toaster can reach the API 137
130URL, you should see a message telling you that Toaster is updating the 138.. code-block:: shell
131layer source information. 139
140 $ bitbake/lib/toaster/manage.py lsupdates
141
142
143If Toaster can reach the API URL, you should see a message telling you that
144Toaster is updating the layer source information.
132 145
133.. _toaster-releases: 146.. _toaster-releases:
134 147
@@ -157,11 +170,11 @@ to build against different revisions of OpenEmbedded and BitBake.
157 170
158As shipped, Toaster is configured to work with the following releases: 171As shipped, Toaster is configured to work with the following releases:
159 172
160- *Yocto Project DISTRO "DISTRO_NAME" or OpenEmbedded "DISTRO_NAME":* 173- *Yocto Project &DISTRO; "&DISTRO_NAME;" or OpenEmbedded "&DISTRO_NAME;":*
161 This release causes your Toaster projects to build against the head 174 This release causes your Toaster projects to build against the head
162 of the DISTRO_NAME_NO_CAP branch at 175 of the &DISTRO_NAME_NO_CAP; branch at
163 https://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=rocko or 176 https://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=&DISTRO_NAME_NO_CAP; or
164 http://git.openembedded.org/openembedded-core/commit/?h=rocko. 177 http://git.openembedded.org/openembedded-core/commit/?h=&DISTRO_NAME_NO_CAP;.
165 178
166- *Yocto Project "Master" or OpenEmbedded "Master":* This release 179- *Yocto Project "Master" or OpenEmbedded "Master":* This release
167 causes your Toaster Projects to build against the head of the master 180 causes your Toaster Projects to build against the head of the master
@@ -224,9 +237,14 @@ particularly useful if your custom configuration defines fewer releases
224or layers than the default fixture files. 237or layers than the default fixture files.
225 238
226The following example sets "name" to "CUSTOM_XML_ONLY" and its value to 239The following example sets "name" to "CUSTOM_XML_ONLY" and its value to
227"True". <object model="orm.toastersetting" pk="99"> <field 240"True".
228type="CharField" name="name">CUSTOM_XML_ONLY</field> <field 241
229type="CharField" name="value">True</field> </object> 242.. code-block:: xml
243
244 <object model="orm.toastersetting" pk="99">
245 <field type="CharField" name="name">CUSTOM_XML_ONLY</field>
246 <field type="CharField" name="value">True</field>
247 </object>
230 248
231Understanding Fixture File Format 249Understanding Fixture File Format
232--------------------------------- 250---------------------------------
@@ -244,10 +262,17 @@ Defining the Default Distro and Other Values
244This section defines the default distro value for new projects. By 262This section defines the default distro value for new projects. By
245default, it reserves the first Toaster Setting record "1". The following 263default, it reserves the first Toaster Setting record "1". The following
246demonstrates how to set the project default value for 264demonstrates how to set the project default value for
247:term:`DISTRO`: <!-- Set the project 265:term:`DISTRO`:
248default value for DISTRO --> <object model="orm.toastersetting" pk="1"> 266
249<field type="CharField" name="name">DEFCONF_DISTRO</field> <field 267.. code-block:: xml
250type="CharField" name="value">poky</field> </object> You can override 268
269 <!-- Set the project default value for DISTRO -->
270 <object model="orm.toastersetting" pk="1">
271 <field type="CharField" name="name">DEFCONF_DISTRO</field>
272 <field type="CharField" name="value">poky</field>
273 </object>
274
275You can override
251other default project values by adding additional Toaster Setting 276other default project values by adding additional Toaster Setting
252sections such as any of the settings coming from the ``settings.xml`` 277sections such as any of the settings coming from the ``settings.xml``
253file. Also, you can add custom values that are included in the BitBake 278file. Also, you can add custom values that are included in the BitBake
@@ -258,40 +283,53 @@ Defining BitBake Version
258~~~~~~~~~~~~~~~~~~~~~~~~ 283~~~~~~~~~~~~~~~~~~~~~~~~
259 284
260The following defines which version of BitBake is used for the following 285The following defines which version of BitBake is used for the following
261release selection: <!-- Bitbake versions which correspond to the 286release selection:
262metadata release --> <object model="orm.bitbakeversion" pk="1"> <field 287
263type="CharField" name="name">rocko</field> <field type="CharField" 288.. code-block:: xml
264name="giturl">git://git.yoctoproject.org/poky</field> <field 289
265type="CharField" name="branch">rocko</field> <field type="CharField" 290 <!-- Bitbake versions which correspond to the metadata release -->
266name="dirpath">bitbake</field> </object> 291 <object model="orm.bitbakeversion" pk="1">
292 <field type="CharField" name="name">&DISTRO_NAME_NO_CAP;</field>
293 <field type="CharField" name="giturl">git://git.yoctoproject.org/poky</field>
294 <field type="CharField" name="branch">&DISTRO_NAME_NO_CAP;</field>
295 <field type="CharField" name="dirpath">bitbake</field>
296 </object>
267 297
268.. _defining-releases: 298.. _defining-releases:
269 299
270Defining Release 300Defining Release
271~~~~~~~~~~~~~~~~ 301~~~~~~~~~~~~~~~~
272 302
273The following defines the releases when you create a new project. <!-- 303The following defines the releases when you create a new project:
274Releases available --> <object model="orm.release" pk="1"> <field 304
275type="CharField" name="name">rocko</field> <field type="CharField" 305.. code-block:: xml
276name="description">Yocto Project 2.4 "Rocko"</field> <field 306
277rel="ManyToOneRel" to="orm.bitbakeversion" 307 <!-- Releases available -->
278name="bitbake_version">1</field> <field type="CharField" 308 <object model="orm.release" pk="1">
279name="branch_name">rocko</field> <field type="TextField" 309 <field type="CharField" name="name">&DISTRO_NAME_NO_CAP;</field>
280name="helptext">Toaster will run your builds using the tip of the <a 310 <field type="CharField" name="description">Yocto Project &DISTRO; "&DISTRO_NAME;"</field>
281href="http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=rocko">Yocto 311 <field rel="ManyToOneRel" to="orm.bitbakeversion" name="bitbake_version">1</field>
282Project Rocko branch</a>.</field> </object> The "pk" value must match 312 <field type="CharField" name="branch_name">&DISTRO_NAME_NO_CAP;</field>
283the above respective BitBake version record. 313 <field type="TextField" name="helptext">Toaster will run your builds using the tip of the <a href="http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=&DISTRO_NAME_NO_CAP;">Yocto Project &DISTRO_NAME; branch</a>.</field>
314 </object>
315
316The "pk" value must match the above respective BitBake version record.
284 317
285Defining the Release Default Layer Names 318Defining the Release Default Layer Names
286~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 319~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
287 320
288The following defines the default layers for each release: <!-- Default 321The following defines the default layers for each release:
289project layers for each release --> <object 322
290model="orm.releasedefaultlayer" pk="1"> <field rel="ManyToOneRel" 323.. code-block:: xml
291to="orm.release" name="release">1</field> <field type="CharField" 324
292name="layer_name">openembedded-core</field> </object> The 'pk' values in 325 <!-- Default project layers for each release -->
293the example above should start at "1" and increment uniquely. You can 326 <object model="orm.releasedefaultlayer" pk="1">
294use the same layer name in multiple releases. 327 <field rel="ManyToOneRel" to="orm.release" name="release">1</field>
328 <field type="CharField" name="layer_name">openembedded-core</field>
329 </object>
330
331The 'pk' values in the example above should start at "1" and increment
332uniquely. You can use the same layer name in multiple releases.
295 333
296Defining Layer Definitions 334Defining Layer Definitions
297~~~~~~~~~~~~~~~~~~~~~~~~~~ 335~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -302,35 +340,42 @@ for each respective release. You must have one ``orm.layer`` entry for
302each layer. Then, with each entry you need a set of 340each layer. Then, with each entry you need a set of
303``orm.layer_version`` entries that connects the layer with each release 341``orm.layer_version`` entries that connects the layer with each release
304that includes the layer. In general all releases include the layer. 342that includes the layer. In general all releases include the layer.
305<object model="orm.layer" pk="1"> <field type="CharField" 343
306name="name">openembedded-core</field> <field type="CharField" 344.. code-block:: xml
307name="layer_index_url"></field> <field type="CharField" 345
308name="vcs_url">git://git.yoctoproject.org/poky</field> <field 346 <object model="orm.layer" pk="1">
309type="CharField" 347 <field type="CharField" name="name">openembedded-core</field>
310name="vcs_web_url">http://git.yoctoproject.org/cgit/cgit.cgi/poky</field> 348 <field type="CharField" name="layer_index_url"></field>
311<field type="CharField" 349 <field type="CharField" name="vcs_url">git://git.yoctoproject.org/poky</field>
312name="vcs_web_tree_base_url">http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%</field> 350 <field type="CharField" name="vcs_web_url">http://git.yoctoproject.org/cgit/cgit.cgi/poky</field>
313<field type="CharField" 351 <field type="CharField" name="vcs_web_tree_base_url">http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%</field>
314name="vcs_web_file_base_url">http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%</field> 352 <field type="CharField" name="vcs_web_file_base_url">http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%</field>
315</object> <object model="orm.layer_version" pk="1"> <field 353 </object>
316rel="ManyToOneRel" to="orm.layer" name="layer">1</field> <field 354 <object model="orm.layer_version" pk="1">
317type="IntegerField" name="layer_source">0</field> <field 355 <field rel="ManyToOneRel" to="orm.layer" name="layer">1</field>
318rel="ManyToOneRel" to="orm.release" name="release">1</field> <field 356 <field type="IntegerField" name="layer_source">0</field>
319type="CharField" name="branch">rocko</field> <field type="CharField" 357 <field rel="ManyToOneRel" to="orm.release" name="release">1</field>
320name="dirpath">meta</field> </object> <object model="orm.layer_version" 358 <field type="CharField" name="branch">&DISTRO_NAME_NO_CAP;</field>
321pk="2"> <field rel="ManyToOneRel" to="orm.layer" name="layer">1</field> 359 <field type="CharField" name="dirpath">meta</field>
322<field type="IntegerField" name="layer_source">0</field> <field 360 </object> <object model="orm.layer_version" pk="2">
323rel="ManyToOneRel" to="orm.release" name="release">2</field> <field 361 <field rel="ManyToOneRel" to="orm.layer" name="layer">1</field>
324type="CharField" name="branch">HEAD</field> <field type="CharField" 362 <field type="IntegerField" name="layer_source">0</field>
325name="commit">HEAD</field> <field type="CharField" 363 <field rel="ManyToOneRel" to="orm.release" name="release">2</field>
326name="dirpath">meta</field> </object> <object model="orm.layer_version" 364 <field type="CharField" name="branch">HEAD</field>
327pk="3"> <field rel="ManyToOneRel" to="orm.layer" name="layer">1</field> 365 <field type="CharField" name="commit">HEAD</field>
328<field type="IntegerField" name="layer_source">0</field> <field 366 <field type="CharField" name="dirpath">meta</field>
329rel="ManyToOneRel" to="orm.release" name="release">3</field> <field 367 </object>
330type="CharField" name="branch">master</field> <field type="CharField" 368 <object model="orm.layer_version" pk="3">
331name="dirpath">meta</field> </object> The layer "pk" values above must 369 <field rel="ManyToOneRel" to="orm.layer" name="layer">1</field>
332be unique, and typically start at "1". The layer version "pk" values 370 <field type="IntegerField" name="layer_source">0</field>
333must also be unique across all layers, and typically start at "1". 371 <field rel="ManyToOneRel" to="orm.release" name="release">3</field>
372 <field type="CharField" name="branch">master</field>
373 <field type="CharField" name="dirpath">meta</field>
374 </object>
375
376The layer "pk" values above must be unique, and typically start at "1". The
377layer version "pk" values must also be unique across all layers, and typically
378start at "1".
334 379
335Remote Toaster Monitoring 380Remote Toaster Monitoring
336========================= 381=========================
@@ -350,26 +395,53 @@ Checking Health
350 395
351Before you use remote Toaster monitoring, you should do a health check. 396Before you use remote Toaster monitoring, you should do a health check.
352To do this, ping the Toaster server using the following call to see if 397To do this, ping the Toaster server using the following call to see if
353it is still alive: http://host:port/health Be sure to provide values for 398it is still alive::
354host and port. If the server is alive, you will get the response HTML: 399
355<!DOCTYPE html> <html lang="en"> <head><title>Toaster 400 http://host:port/health
356Health</title></head> <body>Ok</body> </html> 401
402Be sure to provide values for host and port. If the server is alive, you will
403get the response HTML:
404
405.. code-block:: html
406
407 <!DOCTYPE html>
408 <html lang="en">
409 <head><title>Toaster Health</title></head>
410 <body>Ok</body>
411 </html>
357 412
358Determining Status of Builds in Progress 413Determining Status of Builds in Progress
359---------------------------------------- 414----------------------------------------
360 415
361Sometimes it is useful to determine the status of a build in progress. 416Sometimes it is useful to determine the status of a build in progress.
362To get the status of pending builds, use the following call: 417To get the status of pending builds, use the following call::
363http://host:port/toastergui/api/building Be sure to provide values for 418
364host and port. The output is a JSON file that itemizes all builds in 419 http://host:port/toastergui/api/building
365progress. This file includes the time in seconds since each respective 420
366build started as well as the progress of the cloning, parsing, and task 421Be sure to provide values for host and port. The output is a JSON file that
367execution. The following is sample output for a build in progress: 422itemizes all builds in progress. This file includes the time in seconds since
368{"count": 1, "building": [ {"machine": "beaglebone", "seconds": 423each respective build started as well as the progress of the cloning, parsing,
369"463.869", "task": "927:2384", "distro": "poky", "clone": "1:1", "id": 424and task execution. The following is sample output for a build in progress:
3702, "start": "2017-09-22T09:31:44.887Z", "name": "20170922093200", 425
371"parse": "818:818", "project": "my_rocko", "target": 426.. code-block:: JSON
372"core-image-minimal" }] } The JSON data for this query is returned in a 427
428 {"count": 1,
429 "building": [
430 {"machine": "beaglebone",
431 "seconds": "463.869",
432 "task": "927:2384",
433 "distro": "poky",
434 "clone": "1:1",
435 "id": 2,
436 "start": "2017-09-22T09:31:44.887Z",
437 "name": "20170922093200",
438 "parse": "818:818",
439 "project": "my_rocko",
440 "target": "core-image-minimal"
441 }]
442 }
443
444The JSON data for this query is returned in a
373single line. In the previous example the line has been artificially 445single line. In the previous example the line has been artificially
374split for readability. 446split for readability.
375 447
@@ -377,14 +449,33 @@ Checking Status of Builds Completed
377----------------------------------- 449-----------------------------------
378 450
379Once a build is completed, you get the status when you use the following 451Once a build is completed, you get the status when you use the following
380call: http://host:port/toastergui/api/builds Be sure to provide values 452call::
381for host and port. The output is a JSON file that itemizes all complete 453
382builds, and includes build summary information. The following is sample 454 http://host:port/toastergui/api/builds
383output for a completed build: {"count": 1, "builds": [ {"distro": 455
384"poky", "errors": 0, "machine": "beaglebone", "project": "my_rocko", 456Be sure to provide values for host and port. The output is a JSON file that
385"stop": "2017-09-22T09:26:36.017Z", "target": "quilt-native", "seconds": 457itemizes all complete builds, and includes build summary information. The
386"78.193", "outcome": "Succeeded", "id": 1, "start": 458following is sample output for a completed build:
387"2017-09-22T09:25:17.824Z", "warnings": 1, "name": "20170922092618" }] } 459
460.. code-block:: JSON
461
462 {"count": 1,
463 "builds": [
464 {"distro": "poky",
465 "errors": 0,
466 "machine": "beaglebone",
467 "project": "my_rocko",
468 "stop": "2017-09-22T09:26:36.017Z",
469 "target": "quilt-native",
470 "seconds": "78.193",
471 "outcome": "Succeeded",
472 "id": 1,
473 "start": "2017-09-22T09:25:17.824Z",
474 "warnings": 1,
475 "name": "20170922092618"
476 }]
477 }
478
388The JSON data for this query is returned in a single line. In the 479The JSON data for this query is returned in a single line. In the
389previous example the line has been artificially split for readability. 480previous example the line has been artificially split for readability.
390 481
@@ -392,22 +483,39 @@ Determining Status of a Specific Build
392-------------------------------------- 483--------------------------------------
393 484
394Sometimes it is useful to determine the status of a specific build. To 485Sometimes it is useful to determine the status of a specific build. To
395get the status of a specific build, use the following call: 486get the status of a specific build, use the following call::
396http://host:port/toastergui/api/build/ID Be sure to provide values for 487
488 http://host:port/toastergui/api/build/ID
489
490Be sure to provide values for
397host, port, and ID. You can find the value for ID from the Builds 491host, port, and ID. You can find the value for ID from the Builds
398Completed query. See the "`Checking Status of Builds 492Completed query. See the ":ref:`toaster-manual/toaster-manual-reference:checking status of builds completed`"
399Completed <#checking-status-of-builds-completed>`__" section for more 493section for more information.
400information.
401 494
402The output is a JSON file that itemizes the specific build and includes 495The output is a JSON file that itemizes the specific build and includes
403build summary information. The following is sample output for a specific 496build summary information. The following is sample output for a specific
404build: {"build": {"distro": "poky", "errors": 0, "machine": 497build:
405"beaglebone", "project": "my_rocko", "stop": "2017-09-22T09:26:36.017Z", 498
406"target": "quilt-native", "seconds": "78.193", "outcome": "Succeeded", 499.. code-block:: JSON
407"id": 1, "start": "2017-09-22T09:25:17.824Z", "warnings": 1, "name": 500
408"20170922092618", "cooker_log": 501 {"build":
409"/opt/user/poky/build-toaster-2/tmp/log/cooker/beaglebone/build_20170922_022607.991.log" 502 {"distro": "poky",
410} } The JSON data for this query is returned in a single line. In the 503 "errors": 0,
504 "machine": "beaglebone",
505 "project": "my_rocko",
506 "stop": "2017-09-22T09:26:36.017Z",
507 "target": "quilt-native",
508 "seconds": "78.193",
509 "outcome": "Succeeded",
510 "id": 1,
511 "start": "2017-09-22T09:25:17.824Z",
512 "warnings": 1,
513 "name": "20170922092618",
514 "cooker_log": "/opt/user/poky/build-toaster-2/tmp/log/cooker/beaglebone/build_20170922_022607.991.log"
515 }
516 }
517
518The JSON data for this query is returned in a single line. In the
411previous example the line has been artificially split for readability. 519previous example the line has been artificially split for readability.
412 520
413.. _toaster-useful-commands: 521.. _toaster-useful-commands:
@@ -419,7 +527,7 @@ In addition to the web user interface and the scripts that start and
419stop Toaster, command-line commands exist through the ``manage.py`` 527stop Toaster, command-line commands exist through the ``manage.py``
420management script. You can find general documentation on ``manage.py`` 528management script. You can find general documentation on ``manage.py``
421at the 529at the
422`Django <https://docs.djangoproject.com/en/1.7/topics/settings/>`__ 530`Django <https://docs.djangoproject.com/en/2.2/topics/settings/>`__
423site. However, several ``manage.py`` commands have been created that are 531site. However, several ``manage.py`` commands have been created that are
424specific to Toaster and are used to control configuration and back-end 532specific to Toaster and are used to control configuration and back-end
425tasks. You can locate these commands in the 533tasks. You can locate these commands in the
@@ -446,19 +554,31 @@ tasks. You can locate these commands in the
446-------------- 554--------------
447 555
448The ``buildslist`` command lists all builds that Toaster has recorded. 556The ``buildslist`` command lists all builds that Toaster has recorded.
449Access the command as follows: $ bitbake/lib/toaster/manage.py 557Access the command as follows:
450buildslist The command returns a list, which includes numeric 558
559.. code-block:: shell
560
561 $ bitbake/lib/toaster/manage.py buildslist
562
563The command returns a list, which includes numeric
451identifications, of the builds that Toaster has recorded in the current 564identifications, of the builds that Toaster has recorded in the current
452database. 565database.
453 566
454You need to run the ``buildslist`` command first to identify existing 567You need to run the ``buildslist`` command first to identify existing
455builds in the database before using the 568builds in the database before using the
456```builddelete`` <#toaster-command-builddelete>`__ command. Here is an 569:ref:`toaster-manual/toaster-manual-reference:\`\`builddelete\`\`` command. Here is an
457example that assumes default repository and build directory names: $ cd 570example that assumes default repository and build directory names:
458~/poky/build $ python ../bitbake/lib/toaster/manage.py buildslist If 571
459your Toaster database had only one build, the above ``buildslist`` 572.. code-block:: shell
460command would return something like the following: 1: qemux86 poky 573
461core-image-minimal 574 $ cd ~/poky/build
575 $ python ../bitbake/lib/toaster/manage.py buildslist
576
577If your Toaster database had only one build, the above
578:ref:`toaster-manual/toaster-manual-reference:\`\`buildslist\`\``
579command would return something like the following::
580
581 1: qemux86 poky core-image-minimal
462 582
463.. _toaster-command-builddelete: 583.. _toaster-command-builddelete:
464 584
@@ -466,14 +586,19 @@ core-image-minimal
466--------------- 586---------------
467 587
468The ``builddelete`` command deletes data associated with a build. Access 588The ``builddelete`` command deletes data associated with a build. Access
469the command as follows: $ bitbake/lib/toaster/manage.py builddelete 589the command as follows:
470build_id The command deletes all the build data for the specified 590
591.. code-block::
592
593 $ bitbake/lib/toaster/manage.py builddelete build_id
594
595The command deletes all the build data for the specified
471build_id. This command is useful for removing old and unused data from 596build_id. This command is useful for removing old and unused data from
472the database. 597the database.
473 598
474Prior to running the ``builddelete`` command, you need to get the ID 599Prior to running the ``builddelete`` command, you need to get the ID
475associated with builds by using the 600associated with builds by using the
476```buildslist`` <#toaster-command-buildslist>`__ command. 601:ref:`toaster-manual/toaster-manual-reference:\`\`buildslist\`\`` command.
477 602
478.. _toaster-command-perf: 603.. _toaster-command-perf:
479 604
@@ -481,9 +606,14 @@ associated with builds by using the
481-------- 606--------
482 607
483The ``perf`` command measures Toaster performance. Access the command as 608The ``perf`` command measures Toaster performance. Access the command as
484follows: $ bitbake/lib/toaster/manage.py perf The command is a sanity 609follows:
485check that returns page loading times in order to identify performance 610
486problems. 611.. code-block:: shell
612
613 $ bitbake/lib/toaster/manage.py perf
614
615The command is a sanity check that returns page loading times in order to
616identify performance problems.
487 617
488.. _toaster-command-checksettings: 618.. _toaster-command-checksettings:
489 619
@@ -491,7 +621,12 @@ problems.
491----------------- 621-----------------
492 622
493The ``checksettings`` command verifies existing Toaster settings. Access 623The ``checksettings`` command verifies existing Toaster settings. Access
494the command as follows: $ bitbake/lib/toaster/manage.py checksettings 624the command as follows:
625
626.. code-block:: shell
627
628 $ bitbake/lib/toaster/manage.py checksettings
629
495Toaster uses settings that are based on the database to configure the 630Toaster uses settings that are based on the database to configure the
496building tasks. The ``checksettings`` command verifies that the database 631building tasks. The ``checksettings`` command verifies that the database
497settings are valid in the sense that they have the minimal information 632settings are valid in the sense that they have the minimal information
@@ -499,10 +634,15 @@ needed to start a build.
499 634
500In order for the ``checksettings`` command to work, the database must be 635In order for the ``checksettings`` command to work, the database must be
501correctly set up and not have existing data. To be sure the database is 636correctly set up and not have existing data. To be sure the database is
502ready, you can run the following: $ bitbake/lib/toaster/mana​ge.py 637ready, you can run the following:
503syncdb $ bitbake/lib/toaster/mana​ge.py migrate orm $ 638
504bitbake/lib/toaster/mana​ge.py migrate bldcontrol After running these 639.. code-block:: shell
505commands, you can run the ``checksettings`` command. 640
641 $ bitbake/lib/toaster/manage.py syncdb
642 $ bitbake/lib/toaster/manage.py migrate orm
643 $ bitbake/lib/toaster/manage.py migrate bldcontrol
644
645After running these commands, you can run the ``checksettings`` command.
506 646
507.. _toaster-command-runbuilds: 647.. _toaster-command-runbuilds:
508 648
@@ -510,8 +650,13 @@ commands, you can run the ``checksettings`` command.
510------------- 650-------------
511 651
512The ``runbuilds`` command launches scheduled builds. Access the command 652The ``runbuilds`` command launches scheduled builds. Access the command
513as follows: $ bitbake/lib/toaster/manage.py runbuilds The ``runbuilds`` 653as follows:
514command checks if scheduled builds exist in the database and then 654
515launches them per schedule. The command returns after the builds start 655.. code-block:: shell
516but before they complete. The Toaster Logging Interface records and 656
657 $ bitbake/lib/toaster/manage.py runbuilds
658
659The ``runbuilds`` command checks if scheduled builds exist in the database
660and then launches them per schedule. The command returns after the builds
661start but before they complete. The Toaster Logging Interface records and
517updates the database when the builds complete. 662updates the database when the builds complete.
diff --git a/documentation/toaster-manual/toaster-manual-setup-and-use.rst b/documentation/toaster-manual/toaster-manual-setup-and-use.rst
index 1ff28395f3..42d868bbe0 100644
--- a/documentation/toaster-manual/toaster-manual-setup-and-use.rst
+++ b/documentation/toaster-manual/toaster-manual-setup-and-use.rst
@@ -1,4 +1,6 @@
1.. SPDX-License-Identifier: CC-BY-2.0-UK 1.. SPDX-License-Identifier: CC-BY-2.0-UK
2.. Set default pygment highlighting to 'shell' for this document
3.. highlight:: shell
2 4
3**************************** 5****************************
4Setting Up and Using Toaster 6Setting Up and Using Toaster
@@ -8,28 +10,41 @@ Starting Toaster for Local Development
8====================================== 10======================================
9 11
10Once you have set up the Yocto Project and installed the Toaster system 12Once you have set up the Yocto Project and installed the Toaster system
11dependencies as described in the "`Preparing to Use 13dependencies as described in the ":ref:`toaster-manual/toaster-manual-start:Preparing to Use
12Toaster <#toaster-manual-start>`__" chapter, you are ready to start 14Toaster`" chapter, you are ready to start
13Toaster. 15Toaster.
14 16
15Navigate to the root of your 17Navigate to the root of your
16:term:`Source Directory` (e.g. ``poky``): $ 18:term:`Source Directory` (e.g. ``poky``)::
17cd poky Once in that directory, source the build environment script: $ 19
18source oe-init-build-env Next, from the build directory (e.g. 20 $ cd poky
19``poky/build``), start Toaster using this command: $ source toaster 21
20start You can now run your builds from the command line, or with Toaster 22Once in that directory, source the build environment script::
21as explained in section "`Using the Toaster Web 23
22Interface <#using-the-toaster-web-interface>`__". 24 $ source oe-init-build-env
25
26Next, from the build directory (e.g.
27``poky/build``), start Toaster using this command::
28
29 $ source toaster start
30
31You can now run your builds from the command line, or with Toaster
32as explained in section
33":ref:`toaster-manual/toaster-manual-setup-and-use:using the toaster web interface`".
23 34
24To access the Toaster web interface, open your favorite browser and 35To access the Toaster web interface, open your favorite browser and
25enter the following: http://127.0.0.1:8000 36enter the following::
37
38 http://127.0.0.1:8000
26 39
27Setting a Different Port 40Setting a Different Port
28======================== 41========================
29 42
30By default, Toaster starts on port 8000. You can use the ``WEBPORT`` 43By default, Toaster starts on port 8000. You can use the ``WEBPORT``
31parameter to set a different port. For example, the following command 44parameter to set a different port. For example, the following command
32sets the port to "8400": $ source toaster start webport=8400 45sets the port to "8400"::
46
47 $ source toaster start webport=8400
33 48
34Setting Up Toaster Without a Web Server 49Setting Up Toaster Without a Web Server
35======================================= 50=======================================
@@ -54,8 +69,11 @@ Toaster environment. Before closing the environment, however, you should
54allow a few minutes to ensure the complete transfer of its BitBake build 69allow a few minutes to ensure the complete transfer of its BitBake build
55statistics to the Toaster database. If you have a separate Toaster web 70statistics to the Toaster database. If you have a separate Toaster web
56server instance running, you can watch this command-line build’s 71server instance running, you can watch this command-line build’s
57progress and examine the results as soon as they are posted: $ source 72progress and examine the results as soon as they are posted::
58toaster start noweb $ bitbake target $ source toaster stop 73
74 $ source toaster start noweb
75 $ bitbake target
76 $ source toaster stop
59 77
60Setting Up Toaster Without a Build Server 78Setting Up Toaster Without a Build Server
61========================================= 79=========================================
@@ -69,23 +87,27 @@ disabled. Doing so is useful for the following:
69- Allowing only local command-line builds to be captured into the 87- Allowing only local command-line builds to be captured into the
70 Toaster database. 88 Toaster database.
71 89
72Use the following command to set up Toaster without a build server: $ 90Use the following command to set up Toaster without a build server::
73source toaster start nobuild webport=port 91
92 $ source toaster start nobuild webport=port
74 93
75Setting up External Access 94Setting up External Access
76========================== 95==========================
77 96
78By default, Toaster binds to the loop back address (i.e. localhost), 97By default, Toaster binds to the loop back address (i.e. ``localhost``),
79which does not allow access from external hosts. To allow external 98which does not allow access from external hosts. To allow external
80access, use the ``WEBPORT`` parameter to open an address that connects 99access, use the ``WEBPORT`` parameter to open an address that connects
81to the network, specifically the IP address that your NIC uses to 100to the network, specifically the IP address that your NIC uses to
82connect to the network. You can also bind to all IP addresses the 101connect to the network. You can also bind to all IP addresses the
83computer supports by using the shortcut "0.0.0.0:port". 102computer supports by using the shortcut "0.0.0.0:port".
84 103
85The following example binds to all IP addresses on the host: $ source 104The following example binds to all IP addresses on the host::
86toaster start webport=0.0.0.0:8400 This example binds to a specific IP 105
87address on the host's NIC: $ source toaster start 106 $ source toaster start webport=0.0.0.0:8400
88webport=192.168.1.1:8400 107
108This example binds to a specific IP address on the host's NIC::
109
110 $ source toaster start webport=192.168.1.1:8400
89 111
90The Directory for Cloning Layers 112The Directory for Cloning Layers
91================================ 113================================
@@ -126,34 +148,43 @@ parameters.
126To access the Django administration interface, you must create a 148To access the Django administration interface, you must create a
127superuser by following these steps: 149superuser by following these steps:
128 150
1291. If you used ``pip3``, which is recommended, to set up the Toaster 151#. If you used ``pip3``, which is recommended, to set up the Toaster
130 system dependencies, you need be sure the local user path is in your 152 system dependencies, you need be sure the local user path is in your
131 ``PATH`` list. To append the pip3 local user path, use the following 153 ``PATH`` list. To append the pip3 local user path, use the following
132 command: $ export PATH=$PATH:$HOME/.local/bin 154 command::
133 155
1342. From the directory containing the Toaster database, which by default 156 $ export PATH=$PATH:$HOME/.local/bin
157
158#. From the directory containing the Toaster database, which by default
135 is the :term:`Build Directory`, 159 is the :term:`Build Directory`,
136 invoke the ``createsuperuser`` command from ``manage.py``: $ cd 160 invoke the ``createsuperuser`` command from ``manage.py``::
137 ~/poky/build $ ../bitbake/lib/toaster/manage.py createsuperuser 161
162 $ cd ~/poky/build
163 $ ../bitbake/lib/toaster/manage.py createsuperuser
138 164
1393. Django prompts you for the username, which you need to provide. 165#. Django prompts you for the username, which you need to provide.
140 166
1414. Django prompts you for an email address, which is optional. 167#. Django prompts you for an email address, which is optional.
142 168
1435. Django prompts you for a password, which you must provide. 169#. Django prompts you for a password, which you must provide.
144 170
1456. Django prompts you to re-enter your password for verification. 171#. Django prompts you to re-enter your password for verification.
146 172
147After completing these steps, the following confirmation message 173After completing these steps, the following confirmation message
148appears: Superuser created successfully. 174appears::
175
176 Superuser created successfully.
149 177
150Creating a superuser allows you to access the Django administration 178Creating a superuser allows you to access the Django administration
151interface through a browser. The URL for this interface is the same as 179interface through a browser. The URL for this interface is the same as
152the URL used for the Toaster instance with "/admin" on the end. For 180the URL used for the Toaster instance with "/admin" on the end. For
153example, if you are running Toaster locally, use the following URL: 181example, if you are running Toaster locally, use the following URL::
154http://127.0.0.1:8000/admin You can use the Django administration 182
155interface to set Toaster configuration parameters such as the build 183 http://127.0.0.1:8000/admin
156directory, layer sources, default variable values, and BitBake versions. 184
185You can use the Django administration interface to set Toaster configuration
186parameters such as the build directory, layer sources, default variable
187values, and BitBake versions.
157 188
158.. _toaster-setting-up-a-production-instance-of-toaster: 189.. _toaster-setting-up-a-production-instance-of-toaster:
159 190
@@ -175,12 +206,10 @@ Be sure you meet the following requirements:
175 206
176.. note:: 207.. note::
177 208
178 You must comply with all Apache, 209 You must comply with all Apache, ``mod-wsgi``, and Mysql requirements.
179 mod-wsgi
180 , and Mysql requirements.
181 210
182- Have all the build requirements as described in the "`Preparing to 211- Have all the build requirements as described in the ":ref:`toaster-manual/toaster-manual-start:Preparing to
183 Use Toaster <#toaster-manual-start>`__" chapter. 212 Use Toaster`" chapter.
184 213
185- Have an Apache webserver. 214- Have an Apache webserver.
186 215
@@ -188,17 +217,18 @@ Be sure you meet the following requirements:
188 217
189- Use the Mysql database server. 218- Use the Mysql database server.
190 219
191- If you are using Ubuntu 16.04, run the following: $ sudo apt-get 220- If you are using Ubuntu, run the following::
192 install apache2 libapache2-mod-wsgi-py3 mysql-server python3-pip 221
193 libmysqlclient-dev 222 $ sudo apt-get install apache2 libapache2-mod-wsgi-py3 mysql-server python3-pip libmysqlclient-dev
223
224- If you are using Fedora or a RedHat distribution, run the
225 following::
194 226
195- If you are using Fedora 24 or a RedHat distribution, run the 227 $ sudo dnf install httpd python3-mod_wsgi python3-pip mariadb-server mariadb-devel python3-devel
196 following: $ sudo dnf install httpd python3-mod_wsgi python3-pip
197 mariadb-server mariadb-devel python3-devel
198 228
199- If you are using openSUSE Leap 42.1, run the following: $ sudo zypper 229- If you are using openSUSE, run the following::
200 install apache2 apache2-mod_wsgi-python3 python3-pip mariadb 230
201 mariadb-client python3-devel 231 $ sudo zypper install apache2 apache2-mod_wsgi-python3 python3-pip mariadb mariadb-client python3-devel
202 232
203.. _toaster-installation-steps: 233.. _toaster-installation-steps:
204 234
@@ -207,19 +237,24 @@ Installation
207 237
208Perform the following steps to install Toaster: 238Perform the following steps to install Toaster:
209 239
2101. Create toaster user and set its home directory to 240#. Create toaster user and set its home directory to
211 ``/var/www/toaster``: $ sudo /usr/sbin/useradd toaster -md 241 ``/var/www/toaster``::
212 /var/www/toaster -s /bin/false $ sudo su - toaster -s /bin/bash 242
243 $ sudo /usr/sbin/useradd toaster -md /var/www/toaster -s /bin/false
244 $ sudo su - toaster -s /bin/bash
213 245
2142. Checkout a copy of ``poky`` into the web server directory. You will 246#. Checkout a copy of ``poky`` into the web server directory. You will
215 be using ``/var/www/toaster``: $ git clone 247 be using ``/var/www/toaster``::
216 git://git.yoctoproject.org/poky $ git checkout DISTRO_NAME_NO_CAP
217 248
2183. Install Toaster dependencies using the --user flag which keeps the 249 $ git clone git://git.yoctoproject.org/poky
219 Python packages isolated from your system-provided packages: $ cd 250 $ git checkout &DISTRO_NAME_NO_CAP;
220 /var/www/toaster/ $ pip3 install --user -r 251
221 ./poky/bitbake/toaster-requirements.txt $ pip3 install --user 252#. Install Toaster dependencies using the --user flag which keeps the
222 mysqlclient 253 Python packages isolated from your system-provided packages::
254
255 $ cd /var/www/toaster/
256 $ pip3 install --user -r ./poky/bitbake/toaster-requirements.txt
257 $ pip3 install --user mysqlclient
223 258
224 .. note:: 259 .. note::
225 260
@@ -227,35 +262,60 @@ Perform the following steps to install Toaster:
227 Alternatively, you can use your operating system's package 262 Alternatively, you can use your operating system's package
228 manager to install the packages. 263 manager to install the packages.
229 264
2304. Configure Toaster by editing 265#. Configure Toaster by editing
231 ``/var/www/toaster/poky/bitbake/lib/toaster/toastermain/settings.py`` 266 ``/var/www/toaster/poky/bitbake/lib/toaster/toastermain/settings.py``
232 as follows: 267 as follows:
233 268
234 - Edit the 269 - Edit the
235 `DATABASES <https://docs.djangoproject.com/en/1.11/ref/settings/#databases>`__ 270 `DATABASES <https://docs.djangoproject.com/en/2.2/ref/settings/#databases>`__
236 settings: DATABASES = { 'default': { 'ENGINE': 271 settings:
237 'django.db.backends.mysql', 'NAME': 'toaster_data', 'USER': 272
238 'toaster', 'PASSWORD': 'yourpasswordhere', 'HOST': 'localhost', 273 .. code-block:: python
239 'PORT': '3306', } } 274
275 DATABASES = {
276 'default': {
277 'ENGINE': 'django.db.backends.mysql',
278 'NAME': 'toaster_data',
279 'USER': 'toaster',
280 'PASSWORD': 'yourpasswordhere',
281 'HOST': 'localhost',
282 'PORT': '3306',
283 }
284 }
240 285
241 - Edit the 286 - Edit the
242 `SECRET_KEY <https://docs.djangoproject.com/en/1.11/ref/settings/#std:setting-SECRET_KEY>`__: 287 `SECRET_KEY <https://docs.djangoproject.com/en/2.2/ref/settings/#std:setting-SECRET_KEY>`__:
243 SECRET_KEY = 'your_secret_key' 288
289 .. code-block:: python
290
291 SECRET_KEY = 'your_secret_key'
244 292
245 - Edit the 293 - Edit the
246 `STATIC_ROOT <https://docs.djangoproject.com/en/1.11/ref/settings/#std:setting-STATIC_ROOT>`__: 294 `STATIC_ROOT <https://docs.djangoproject.com/en/2.2/ref/settings/#std:setting-STATIC_ROOT>`__:
247 STATIC_ROOT = '/var/www/toaster/static_files/' 295
248 296 .. code-block:: python
2495. Add the database and user to the ``mysql`` server defined earlier: $ 297
250 mysql -u root -p mysql> CREATE DATABASE toaster_data; mysql> CREATE 298 STATIC_ROOT = '/var/www/toaster/static_files/'
251 USER 'toaster'@'localhost' identified by 'yourpasswordhere'; mysql> 299
252 GRANT all on toaster_data.\* to 'toaster'@'localhost'; mysql> quit 300#. Add the database and user to the ``mysql`` server defined earlier::
253 301
2546. Get Toaster to create the database schema, default data, and gather 302 $ mysql -u root -p
255 the statically-served files: $ cd /var/www/toaster/poky/ $ 303 mysql> CREATE DATABASE toaster_data;
256 ./bitbake/lib/toaster/manage.py migrate $ TOASTER_DIR=`pwd\` 304 mysql> CREATE USER 'toaster'@'localhost' identified by 'yourpasswordhere';
257 TEMPLATECONF='poky' \\ ./bitbake/lib/toaster/manage.py checksettings 305 mysql> GRANT all on toaster_data.\* to 'toaster'@'localhost';
258 $ ./bitbake/lib/toaster/manage.py collectstatic In the previous 306 mysql> quit
307
308#. Get Toaster to create the database schema, default data, and gather
309 the statically-served files::
310
311 $ cd /var/www/toaster/poky/
312 $ ./bitbake/lib/toaster/manage.py migrate
313 $ TOASTER_DIR=`pwd\` TEMPLATECONF='poky' \
314 ./bitbake/lib/toaster/manage.py checksettings
315 $ ./bitbake/lib/toaster/manage.py collectstatic
316
317
318 In the previous
259 example, from the ``poky`` directory, the ``migrate`` command 319 example, from the ``poky`` directory, the ``migrate`` command
260 ensures the database schema changes have propagated correctly (i.e. 320 ensures the database schema changes have propagated correctly (i.e.
261 migrations). The next line sets the Toaster root directory 321 migrations). The next line sets the Toaster root directory
@@ -264,80 +324,145 @@ Perform the following steps to install Toaster:
264 ``TEMPLATECONF`` value reflects the contents of 324 ``TEMPLATECONF`` value reflects the contents of
265 ``poky/.templateconf``, and by default, should include the string 325 ``poky/.templateconf``, and by default, should include the string
266 "poky". For more information on the Toaster configuration file, see 326 "poky". For more information on the Toaster configuration file, see
267 the "`Configuring Toaster <#configuring-toaster>`__" section. 327 the ":ref:`toaster-manual/toaster-manual-reference:Configuring Toaster`" section.
268 328
269 This line also runs the ``checksettings`` command, which configures 329 This line also runs the ``checksettings`` command, which configures
270 the location of the Toaster :term:`Build Directory`. 330 the location of the Toaster :term:`Build Directory`.
271 The Toaster 331 The Toaster
272 root directory ``TOASTER_DIR`` determines where the Toaster build 332 root directory ``TOASTER_DIR`` determines where the Toaster build
273 directory is created on the file system. In the example above, 333 directory is created on the file system. In the example above,
274 ``TOASTER_DIR`` is set as follows: /var/www/toaster/poky This 334 ``TOASTER_DIR`` is set as follows::
275 setting causes the Toaster build directory to be: 335
276 /var/www/toaster/poky/build 336 /var/www/toaster/poky
337
338
339 This setting causes the Toaster build directory to be::
340
341 /var/www/toaster/poky/build
277 342
278 Finally, the ``collectstatic`` command is a Django framework command 343 Finally, the ``collectstatic`` command is a Django framework command
279 that collects all the statically served files into a designated 344 that collects all the statically served files into a designated
280 directory to be served up by the Apache web server as defined by 345 directory to be served up by the Apache web server as defined by
281 ``STATIC_ROOT``. 346 ``STATIC_ROOT``.
282 347
2837. Test and/or use the Mysql integration with Toaster’s Django web 348#. Test and/or use the Mysql integration with Toaster’s Django web
284 server. At this point, you can start up the normal Toaster Django 349 server. At this point, you can start up the normal Toaster Django
285 web server with the Toaster database in Mysql. You can use this web 350 web server with the Toaster database in Mysql. You can use this web
286 server to confirm that the database migration and data population 351 server to confirm that the database migration and data population
287 from the Layer Index is complete. 352 from the Layer Index is complete.
288 353
289 To start the default Toaster Django web server with the Toaster 354 To start the default Toaster Django web server with the Toaster
290 database now in Mysql, use the standard start commands: $ source 355 database now in Mysql, use the standard start commands::
291 oe-init-build-env $ source toaster start Additionally, if Django is 356
292 sufficient for your requirements, you can use it for your release 357 $ source oe-init-build-env
293 system and migrate later to Apache as your requirements change. 358 $ source toaster start
294 359
2958. Add an Apache configuration file for Toaster to your Apache web 360 Additionally, if Django is sufficient for your requirements, you can use
361 it for your release system and migrate later to Apache as your
362 requirements change.
363
364#. Add an Apache configuration file for Toaster to your Apache web
296 server's configuration directory. If you are using Ubuntu or Debian, 365 server's configuration directory. If you are using Ubuntu or Debian,
297 put the file here: /etc/apache2/conf-available/toaster.conf If you 366 put the file here::
298 are using Fedora or RedHat, put it here: 367
299 /etc/httpd/conf.d/toaster.conf If you are using OpenSUSE, put it 368 /etc/apache2/conf-available/toaster.conf
300 here: /etc/apache2/conf.d/toaster.conf Following is a sample Apache 369
301 configuration for Toaster you can follow: Alias /static 370
302 /var/www/toaster/static_files <Directory 371 If you are using Fedora or RedHat, put it here::
303 /var/www/toaster/static_files> <IfModule mod_access_compat.c> Order 372
304 allow,deny Allow from all </IfModule> <IfModule 373 /etc/httpd/conf.d/toaster.conf
305 !mod_access_compat.c> Require all granted </IfModule> </Directory> 374
306 <Directory /var/www/toaster/poky/bitbake/lib/toaster/toastermain> 375 If you are using OpenSUSE, put it here::
307 <Files "wsgi.py"> Require all granted </Files> </Directory> 376
308 WSGIDaemonProcess toaster_wsgi 377 /etc/apache2/conf.d/toaster.conf
309 python-path=/var/www/toaster/poky/bitbake/lib/toaster:/var/www/toaster/.local/lib/python3.4/site-packages 378
310 WSGIScriptAlias / 379 Following is a sample Apache configuration for Toaster you can follow:
311 "/var/www/toaster/poky/bitbake/lib/toaster/toastermain/wsgi.py" 380
312 <Location /> WSGIProcessGroup toaster_wsgi </Location> If you are 381 .. code-block:: apache
313 using Ubuntu or Debian, you will need to enable the config and 382
314 module for Apache: $ sudo a2enmod wsgi $ sudo a2enconf toaster $ 383 Alias /static /var/www/toaster/static_files
315 chmod +x bitbake/lib/toaster/toastermain/wsgi.py Finally, restart 384 <Directory /var/www/toaster/static_files>
316 Apache to make sure all new configuration is loaded. For Ubuntu, 385 <IfModule mod_access_compat.c>
317 Debian, and OpenSUSE use: $ sudo service apache2 restart For Fedora 386 Order allow,deny
318 and RedHat use: $ sudo service httpd restart 387 Allow from all
319 388 </IfModule>
3209. Prepare the systemd service to run Toaster builds. Here is a sample 389 <IfModule !mod_access_compat.c>
321 configuration file for the service: [Unit] Description=Toaster 390 Require all granted
322 runbuilds [Service] Type=forking User=toaster 391 </IfModule>
323 ExecStart=/usr/bin/screen -d -m -S runbuilds 392 </Directory>
324 /var/www/toaster/poky/bitbake/lib/toaster/runbuilds-service.sh start 393
325 ExecStop=/usr/bin/screen -S runbuilds -X quit 394 <Directory /var/www/toaster/poky/bitbake/lib/toaster/toastermain>
326 WorkingDirectory=/var/www/toaster/poky [Install] 395 <Files "wsgi.py">
327 WantedBy=multi-user.target Prepare the ``runbuilds-service.sh`` 396 Require all granted
328 script that you need to place in the 397 </Files>
398 </Directory>
399
400 WSGIDaemonProcess toaster_wsgi python-path=/var/www/toaster/poky/bitbake/lib/toaster:/var/www/toaster/.local/lib/python3.4/site-packages
401 WSGIScriptAlias / "/var/www/toaster/poky/bitbake/lib/toaster/toastermain/wsgi.py"
402 <Location />
403 WSGIProcessGroup toaster_wsgi
404 </Location>
405
406
407 If you are using Ubuntu or Debian, you will need to enable the config and
408 module for Apache::
409
410 $ sudo a2enmod wsgi
411 $ sudo a2enconf toaster
412 $ chmod +x bitbake/lib/toaster/toastermain/wsgi.py
413
414 Finally, restart Apache to make sure all new configuration is loaded. For Ubuntu,
415 Debian, and OpenSUSE use::
416
417 $ sudo service apache2 restart
418
419 For Fedora and RedHat use::
420
421 $ sudo service httpd restart
422
423#. Prepare the systemd service to run Toaster builds. Here is a sample
424 configuration file for the service:
425
426 .. code-block:: ini
427
428 [Unit]
429 Description=Toaster runbuilds
430
431 [Service]
432 Type=forking User=toaster
433 ExecStart=/usr/bin/screen -d -m -S runbuilds /var/www/toaster/poky/bitbake/lib/toaster/runbuilds-service.sh start
434 ExecStop=/usr/bin/screen -S runbuilds -X quit
435 WorkingDirectory=/var/www/toaster/poky
436
437 [Install]
438 WantedBy=multi-user.target
439
440
441 Prepare the ``runbuilds-service.sh`` script that you need to place in the
329 ``/var/www/toaster/poky/bitbake/lib/toaster/`` directory by setting 442 ``/var/www/toaster/poky/bitbake/lib/toaster/`` directory by setting
330 up executable permissions: #!/bin/bash #export 443 up executable permissions::
331 http_proxy=http://proxy.host.com:8080 #export 444
332 https_proxy=http://proxy.host.com:8080 #export 445 #!/bin/bash
333 GIT_PROXY_COMMAND=$HOME/bin/gitproxy cd ~/poky/ source 446
334 ./oe-init-build-env build source ../bitbake/bin/toaster $1 noweb [ 447 #export http_proxy=http://proxy.host.com:8080
335 "$1" == 'start' ] && /bin/bash 448 #export https_proxy=http://proxy.host.com:8080
336 449 #export GIT_PROXY_COMMAND=$HOME/bin/gitproxy
33710. Run the service: # service runbuilds start Since the service is 450 cd ~/poky/
338 running in a detached screen session, you can attach to it using 451 source ./oe-init-build-env build
339 this command: $ sudo su - toaster $ screen -rS runbuilds You can 452 source ../bitbake/bin/toaster $1 noweb
340 detach from the service again using "Ctrl-a" followed by "d" key 453 [ "$1" == 'start' ] && /bin/bash
454
455#. Run the service::
456
457 $ sudo service runbuilds start
458
459 Since the service is running in a detached screen session, you can
460 attach to it using this command::
461
462 $ sudo su - toaster
463 $ screen -rS runbuilds
464
465 You can detach from the service again using "Ctrl-a" followed by "d" key
341 combination. 466 combination.
342 467
343You can now open up a browser and start using Toaster. 468You can now open up a browser and start using Toaster.
@@ -432,8 +557,9 @@ Additional Information About the Local Yocto Project Release
432------------------------------------------------------------ 557------------------------------------------------------------
433 558
434This section only applies if you have set up Toaster for local 559This section only applies if you have set up Toaster for local
435development, as explained in the "`Starting Toaster for Local 560development, as explained in the
436Development <#starting-toaster-for-local-development>`__" section. 561":ref:`toaster-manual/toaster-manual-setup-and-use:starting toaster for local development`"
562section.
437 563
438When you create a project in Toaster, you will be asked to provide a 564When you create a project in Toaster, you will be asked to provide a
439name and to select a Yocto Project release. One of the release options 565name and to select a Yocto Project release. One of the release options
diff --git a/documentation/toaster-manual/toaster-manual-start.rst b/documentation/toaster-manual/toaster-manual-start.rst
index 1114c04eab..2d612b8938 100644
--- a/documentation/toaster-manual/toaster-manual-start.rst
+++ b/documentation/toaster-manual/toaster-manual-start.rst
@@ -1,4 +1,6 @@
1.. SPDX-License-Identifier: CC-BY-2.0-UK 1.. SPDX-License-Identifier: CC-BY-2.0-UK
2.. Set default pygments highlighting to shell for this document
3.. highlight:: shell
2 4
3************************ 5************************
4Preparing to Use Toaster 6Preparing to Use Toaster
@@ -14,11 +16,11 @@ Setting Up the Basic System Requirements
14 16
15Before you can use Toaster, you need to first set up your build system 17Before you can use Toaster, you need to first set up your build system
16to run the Yocto Project. To do this, follow the instructions in the 18to run the Yocto Project. To do this, follow the instructions in the
17"`Preparing the Build 19":ref:`dev-manual/dev-manual-start:preparing the build host`" section of
18Host <&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host>`__" section of
19the Yocto Project Development Tasks Manual. For Ubuntu/Debian, you might 20the Yocto Project Development Tasks Manual. For Ubuntu/Debian, you might
20also need to do an additional install of pip3. $ sudo apt-get install 21also need to do an additional install of pip3. ::
21python3-pip 22
23 $ sudo apt-get install python3-pip
22 24
23.. _toaster-establishing-toaster-system-dependencies: 25.. _toaster-establishing-toaster-system-dependencies:
24 26
@@ -39,10 +41,17 @@ Install Toaster Packages
39------------------------ 41------------------------
40 42
41You need to install the packages that Toaster requires. Use this 43You need to install the packages that Toaster requires. Use this
42command: $ pip3 install --user -r bitbake/toaster-requirements.txt The 44command::
43previous command installs the necessary Toaster modules into a local 45
46 $ pip3 install --user -r bitbake/toaster-requirements.txt
47
48The previous command installs the necessary Toaster modules into a local
44python 3 cache in your ``$HOME`` directory. The caches is actually 49python 3 cache in your ``$HOME`` directory. The caches is actually
45located in ``$HOME/.local``. To see what packages have been installed 50located in ``$HOME/.local``. To see what packages have been installed
46into your ``$HOME`` directory, do the following: $ pip3 list installed 51into your ``$HOME`` directory, do the following::
47--local If you need to remove something, the following works: $ pip3 52
48uninstall PackageNameToUninstall 53 $ pip3 list installed --local
54
55If you need to remove something, the following works::
56
57 $ pip3 uninstall PackageNameToUninstall