summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--documentation/toaster-manual/toaster-manual-reference.xml446
-rw-r--r--documentation/toaster-manual/toaster-manual-setup-and-use.xml8
2 files changed, 181 insertions, 273 deletions
diff --git a/documentation/toaster-manual/toaster-manual-reference.xml b/documentation/toaster-manual/toaster-manual-reference.xml
index 9aeb1fe576..fe17ea4f95 100644
--- a/documentation/toaster-manual/toaster-manual-reference.xml
+++ b/documentation/toaster-manual/toaster-manual-reference.xml
@@ -254,331 +254,239 @@
254 </section> 254 </section>
255 </section> 255 </section>
256 256
257 <section id='toaster-json-files'> 257 <section id='configuring-toaster'>
258 <title>JSON Files</title> 258 <title>Configuring Toaster</title>
259 259
260 <para> 260 <para>
261 You must configure Toaster before using it. 261 In order to use Toaster, you must configure the database with the
262 Configuration customizes layer source settings and Toaster defaults 262 default content. The following subsections describe various aspects
263 for all users and is performed by the person responsible for 263 of Toaster configuration.
264 Toaster Configuration (i.e the Toaster Administrator).
265 The Toaster Administrator performs this configuration through the
266 Django administration interface.
267 </para> 264 </para>
268 265
269<!-- 266 <section id='configuring-the-workflow'>
270 <para> 267 <title>Configuring the Workflow</title>
271 To make it easier to initially start Toaster, you can import a
272 pre-defined configuration file using the
273 <link linkend='toaster-command-loadconf'><filename>loadconf</filename></link>
274 command.
275 <note>
276 The configuration file is a JSON-formatted text file with
277 specific fields that Toaster recognizes.
278 It is not a data dump from the database, so it cannot be
279 loaded directly in the database.
280 </note>
281 </para>
282-->
283
284 <para>
285 By convention, the supplied configuration files are named
286 <filename>toasterconf.json</filename>.
287 The Toaster Administrator can customize the file prior to loading
288 it into Toaster.
289 The <filename>TOASTER_CONF</filename> variable in the
290 Toaster startup script at <filename>bitbake/bin/toaster</filename>
291 specifies the location of the <filename>toasterconf.json</filename> file.
292 </para>
293
294 <section id='json-file-choices'>
295 <title>Configuration File Choices</title>
296 268
297 <para> 269 <para>
298 Two versions of the configuration file exist: 270 The
299 <itemizedlist> 271 <filename>bldcontrol/management/commands/checksettings.py</filename>
272 file controls workflow configuration.
273 The following steps outline the process to initially populate
274 this database.
275 <orderedlist>
300 <listitem><para> 276 <listitem><para>
301 The 277 The default project settings are set from
302 <filename>meta-poky/conf/toasterconf.json</filename> 278 <filename>orm/fixtures/settings.xml</filename>.
303 in the <filename>conf</filename> directory of the
304 Yocto Project's <filename>meta-poky</filename> layer.
305 This version contains the default Yocto Project
306 configuration for Toaster.
307 You are prompted to select this file during the Toaster
308 set up process if you cloned the
309 <filename>poky</filename> repository (i.e.
310 <filename>&YOCTO_GIT_URL;/poky</filename>).
311 </para></listitem> 279 </para></listitem>
312 <listitem><para> 280 <listitem><para>
313 The <filename>meta/conf/toasterconf.json</filename> 281 The default project distro and layers are added
314 in the <filename>conf</filename> directory of the 282 from <filename>orm/fixtures/poky.xml</filename> if poky
315 OpenEmbedded's <filename>openembedded-core</filename> 283 is installed.
316 layer. 284 If poky is not installed, they are added
317 This version contains the default OpenEmbedded 285 from <filename>orm/fixtures/oe-core.xml</filename>.
318 configuration for Toaster.
319 You are prompted to select this file during the Toaster
320 set up process if you had cloned the
321 <filename>openembedded-core</filename> repository (i.e.
322 <filename>git://git.openembedded.org/openembedded-core</filename>).
323 </para></listitem> 286 </para></listitem>
324 </itemizedlist> 287 <listitem><para>
288 If the <filename>orm/fixtures/custom.xml</filename> file
289 exists, then its values are added.
290 </para></listitem>
291 <listitem><para>
292 The layer index is then scanned and added to the database.
293 </para></listitem>
294 </orderedlist>
295 Once these steps complete, Toaster is set up and ready to use.
325 </para> 296 </para>
326 </section> 297 </section>
327 298
328 <section id='json-structure'> 299 <section id='customizing-pre-set-data'>
329 <title>File Structure</title> 300 <title>Customizing Pre-Set Data</title>
330 301
331 <para> 302 <para>
332 The <filename>toasterconf.json</filename> file consists of 303 The pre-set data for Toaster is easily customizable. You can
333 easily readable areas: configuration, layer sources, BitBake, 304 create the <filename>orm/fixtures/custom.xml</filename> file
334 default release, and releases. 305 to customize the values that go into to the database.
306 Customization is additive,
307 and can either extend or completely replace the existing values.
335 </para> 308 </para>
336 309
337 <section id='json-config-area'> 310 <para>
338 <title>Configuration Area</title> 311 You use the <filename>orm/fixtures/custom.xml</filename> file
312 to change the default project settings for the machine, distro,
313 file images, and layers.
314 When creating a new project, you can use the file to define
315 the offered alternate project release selections.
316 For example, you can add one or more additional selections that
317 present custom layer sets or distros, and any other local or proprietary
318 content.
319 Additionally, you can completely disable the content from the
320 <filename>oe-core.xml</filename> and <filename>poky.xml</filename>
321 files by defining the section shown below in the
322 <filename>settings.xml</filename> file.
323 For example, this option is particularly useful if your custom
324 configuration defines fewer releases or layers than the default
325 fixture files.
326 </para>
339 327
340 <para> 328 <para>
341 This area of the JSON file sets which variables are exposed 329 The following example sets "name" to "CUSTOM_XML_ONLY" and its value
342 to users through the Toaster web interface. 330 to "True".
343 Users can easily edit these variables. 331 <literallayout class='monospaced'>
344 </para> 332 &lt;object model="orm.toastersetting" pk="99"&gt;
333 &lt;field type="CharField" name="name"&gt;CUSTOM_XML_ONLY&lt;/field&gt;
345 334
346 <para> 335 &lt;field type="CharField" name="value"&gt;True&lt;/field&gt;
347 The variables you set here are displayed in the 336 &lt;/object&gt;
348 "Configuration variables" page in Toaster. 337 </literallayout>
349 Minimally, you should set the 338 </para>
350 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> 339 </section>
351 variable, which appears to users as part of the project
352 page in Toaster.
353 </para>
354 340
355 <para> 341 <section id='understanding-fixture-file-format'>
356 Here is the default <filename>config</filename> area: 342 <title>Understanding Fixture File Format</title>
357 <literallayout class='monospaced'>
358 "config": {
359 "MACHINE" : "qemux86",
360 "DISTRO" : "poky",
361 "IMAGE_FSTYPES": "ext3 jffs2 tar.bz2",
362 "IMAGE_INSTALL_append": "",
363 "PACKAGE_CLASSES": "package_rpm",
364 },
365 </literallayout>
366 </para>
367 </section>
368 343
369 <section id='json-layersources-area'> 344 <para>
370 <title>Layer Sources Area</title> 345 The following is an overview of the file format used by the
346 <filename>oe-core.xml</filename>, <filename>poky.xml</filename>,
347 and <filename>custom.xml</filename> files.
348 </para>
371 349
372 <para> 350 <para>
373 This area of the JSON file defines the 351 The following subsections describe each of the sections in the
374 <link linkend='layer-source'>layer sources</link> 352 fixture files, and outline an example section of the XML code.
375 Toaster uses. 353 you can use to help understand this information and create a local
376 Toaster reads layer information from layer sources. 354 <filename>custom.xml</filename> file.
377 Three types of layer sources exist that Toaster 355 </para>
378 recognizes: Local, LayerIndex, and Imported. 356
379 </para> 357 <section id='defining-the-default-distro'>
358 <title>Defining the Default Distro</title>
380 359
381 <para> 360 <para>
382 The Local layer source reads layers from Git clones 361 This section defines the default distro value for new projects.
383 available on your local drive. 362 By default, it reserves the first Toaster Setting record "1".
384 Using a local layer source enables you to easily test 363 The following demonstrates how to set the project default value
385 Toaster. 364 for
365 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>:
366 <literallayout class='monospaced'>
367 &lt;!-- Set the project default value for DISTRO --&gt;
368 &lt;object model="orm.toastersetting" pk="1"&gt;
369 &lt;field type="CharField" name="name"&gt;DEFCONF_DISTRO&lt;/field&gt;
370 &lt;field type="CharField" name="value"&gt;poky&lt;/field&gt;
371 &lt;/object&gt;
372 </literallayout>
386 <note> 373 <note>
387 If you are setting up a hosted version of Toaster, 374 You can override the default value by adding additional
388 it does not make sense to have a local layer source. 375 Toaster Setting sections such as any of the settings coming
376 from the <filename>settings.xml</filename> file.
377 Also, you can add custom values that are included in the
378 BitBake environment.
379 The "pk" values must be unique.
380 By convention, values that set default project values have a
381 "DEFCONF" prefix.
389 </note> 382 </note>
390 </para> 383 </para>
384 </section>
391 385
392 <para> 386 <section id='defining-bitbake-version'>
393 The LayerIndex layer source uses a REST API exposed by 387 <title>Defining BitBake Version</title>
394 instances of the Layer Index application (e.g the public
395 <ulink url='http://layers.openembedded.org/'></ulink>)
396 to read layer data.
397 </para>
398
399 <para>
400 The Imported layer source is reserved for layer data
401 manually introduced by the user or Toaster Administrator
402 through the GUI.
403 This layer source lets users import their own layers
404 and build them with Toaster.
405 You should not remove the imported layer source.
406 </para>
407 388
408 <para> 389 <para>
409 Here is the default <filename>layersources</filename> area: 390 The following defines which version of BitBake is used
391 for the following release selection:
410 <literallayout class='monospaced'> 392 <literallayout class='monospaced'>
411 "layersources": [ 393 &lt;!-- Bitbake versions which correspond to the metadata release --&gt;
412 { 394 &lt;object model="orm.bitbakeversion" pk="1"&gt;
413 "name": "Local Yocto Project", 395 &lt;field type="CharField" name="name"&gt;rocko&lt;/field&gt;
414 "sourcetype": "local", 396 &lt;field type="CharField" name="giturl"&gt;git://git.yoctoproject.org/poky&lt;/field&gt;
415 "apiurl": "../../", 397 &lt;field type="CharField" name="branch"&gt;rocko&lt;/field&gt;
416 "branches": ["HEAD" ], 398 &lt;field type="CharField" name="dirpath"&gt;bitbake&lt;/field&gt;
417 "layers": [ 399 &lt;/object&gt;
418 {
419 "name": "openembedded-core",
420 "local_path": "meta",
421 "vcs_url": "remote:origin",
422 "dirpath": "meta"
423 },
424 {
425 "name": "meta-poky",
426 "local_path": "meta-poky",
427 "vcs_url": "remote:origin",
428 "dirpath": "meta-poky"
429 },
430 {
431 "name": "meta-yocto-bsp",
432 "local_path": "meta-yocto-bsp",
433 "vcs_url": "remote:origin",
434 "dirpath": "meta-yocto-bsp"
435 }
436
437 ]
438 },
439 {
440 "name": "OpenEmbedded",
441 "sourcetype": "layerindex",
442 "apiurl": "http://layers.openembedded.org/layerindex/api/",
443 "branches": ["master", "jethro" ,"fido"]
444 },
445 {
446 "name": "Imported layers",
447 "sourcetype": "imported",
448 "apiurl": "",
449 "branches": ["master", "jethro","fido", "HEAD"]
450
451 }
452 ],
453 </literallayout> 400 </literallayout>
454 </para> 401 </para>
455 </section> 402 </section>
456 403
457 <section id='json-bitbake-area'> 404 <section id='defining-releases'>
458 <title>BitBake Area</title> 405 <title>Defining Release</title>
459
460 <para>
461 This area of the JSON file defines the version of
462 BitBake Toaster uses.
463 As shipped, Toaster is configured to recognize four
464 versions of BitBake: master, fido, jethro, and HEAD.
465 <note>
466 HEAD is a special option that builds whatever is
467 available on disk, without checking out any remote
468 Git repositories.
469 </note>
470 </para>
471 406
472 <para> 407 <para>
473 Here is the default <filename>bitbake</filename> area: 408 The following defines the releases when you create a new
409 project.
474 <literallayout class='monospaced'> 410 <literallayout class='monospaced'>
475 "bitbake" : [ 411 &lt;!-- Releases available --&gt;
476 { 412 &lt;object model="orm.release" pk="1"&gt;
477 "name": "master", 413 &lt;field type="CharField" name="name"&gt;rocko&lt;/field&gt;
478 "giturl": "remote:origin", 414 &lt;field type="CharField" name="description"&gt;Yocto Project 2.4 "Rocko"&lt;/field&gt;
479 "branch": "master", 415 &lt;field rel="ManyToOneRel" to="orm.bitbakeversion" name="bitbake_version"&gt;1&lt;/field&gt;
480 "dirpath": "bitbake" 416 &lt;field type="CharField" name="branch_name"&gt;rocko&lt;/field&gt;
481 }, 417 &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;
482 { 418 &lt;/object&gt;
483 "name": "jethro",
484 "giturl": "remote:origin",
485 "branch": "jethro",
486 "dirpath": "bitbake"
487 },
488 {
489 "name": "fido",
490 "giturl": "remote:origin",
491 "branch": "fido",
492 "dirpath": "bitbake"
493 },
494 {
495 "name": "HEAD",
496 "giturl": "remote:origin",
497 "branch": "HEAD",
498 "dirpath": "bitbake"
499 }
500 ],
501 </literallayout> 419 </literallayout>
420 The "pk" value must match the above respective BitBake
421 version record.
502 </para> 422 </para>
503 </section> 423 </section>
504 424
505 <section id='json-default-area'> 425 <section id='defining-the-release-default-layer-names'>
506 <title>Default Area</title> 426 <title>Defining the Release Default Layer Names</title>
507 427
508 <para> 428 <para>
509 This area of the JSON file establishes a default 429 The following defines the default layers for each release:
510 release used by Toaster.
511 As shipped, Toaster uses the "master" release.
512 </para>
513
514 <para>
515 Here is the statement in the JSON file that establishes
516 the default release:
517 <literallayout class='monospaced'> 430 <literallayout class='monospaced'>
518 "defaultrelease": "master", 431 &lt;!-- Default project layers for each release --&gt;
432 &lt;object model="orm.releasedefaultlayer" pk="1"&gt;
433 &lt;field rel="ManyToOneRel" to="orm.release" name="release"&gt;1&lt;/field&gt;
434 &lt;field type="CharField" name="layer_name"&gt;openembedded-core&lt;/field&gt;
435 &lt;/object&gt;
519 </literallayout> 436 </literallayout>
437 The 'pk' values in the example above should start at "1" and increment
438 uniquely.
439 You can use the same layer name in multiple releases.
520 </para> 440 </para>
521 </section> 441 </section>
522 442
523 <section id='json-releases-area'> 443 <section id='defining-layer-definitions'>
524 <title>Releases Area</title> 444 <title>Defining Layer Definitions</title>
525 445
526 <para> 446 <para>
527 This area of the JSON file defines the versions of the 447 Layer definitions are the most complex.
528 OpenEmbedded build system Toaster recognizes. 448 The following defines each of the layers, and then defines the exact layer
529 As shipped, Toaster is configured to work with the four 449 version of the layer used for each respective release.
530 releases described in the
531 "<link linkend='toaster-releases-supported'>Pre-Configured Releases</link>"
532 section.
533 </para>
534
535 <para>
536 Here is the default <filename>releases</filename> area:
537 <literallayout class='monospaced'> 450 <literallayout class='monospaced'>
538 "releases": [ 451 &lt;object model="orm.layer" pk="1"&gt;
539 { 452 &lt;field type="CharField" name="name"&gt;openembedded-core&lt;/field&gt;
540 "name": "master", 453 &lt;field type="CharField" name="layer_index_url"&gt;&lt;/field&gt;
541 "description": "Yocto Project master", 454 &lt;field type="CharField" name="vcs_url"&gt;git://git.yoctoproject.org/poky&lt;/field&gt;
542 "bitbake": "master", 455 &lt;field type="CharField" name="vcs_web_url"&gt;http://git.yoctoproject.org/cgit/cgit.cgi/poky&lt;/field&gt;
543 "branch": "master", 456 &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;
544 "defaultlayers": [ "openembedded-core", "meta-poky", "meta-yocto-bsp"], 457 &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;
545 "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 }, 458 &lt;/object&gt;
546 "helptext": "Toaster will run your builds using the tip of the &lt;a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/\"&gt;Yocto Project master branch&lt;/a&gt;, where active development takes place. This is not a stable branch, so your builds might not work as expected." 459 &lt;object model="orm.layer_version" pk="1"&gt;
547 }, 460 &lt;field rel="ManyToOneRel" to="orm.layer" name="layer"&gt;1&lt;/field&gt;
548 { 461 &lt;field type="IntegerField" name="layer_source"&gt;0&lt;/field&gt;
549 "name": "jethro", 462 &lt;field rel="ManyToOneRel" to="orm.release" name="release"&gt;1&lt;/field&gt;
550 "description": "Yocto Project 2.0 Jethro", 463 &lt;field type="CharField" name="branch"&gt;rocko&lt;/field&gt;
551 "bitbake": "jethro", 464 &lt;field type="CharField" name="dirpath"&gt;meta&lt;/field&gt;
552 "branch": "jethro", 465 &lt;/object&gt;
553 "defaultlayers": [ "openembedded-core", "meta-poky", "meta-yocto-bsp"], 466 &lt;object model="orm.layer_version" pk="2"&gt;
554 "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 }, 467 &lt;field rel="ManyToOneRel" to="orm.layer" name="layer"&gt;1&lt;/field&gt;
555 "helptext": "Toaster will run your builds with the tip of the &lt;a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=jethro\"&gt;Yocto Project 2.0 \"Jethro\"&lt;/a&gt; branch." 468 &lt;field type="IntegerField" name="layer_source"&gt;0&lt;/field&gt;
556 }, 469 &lt;field rel="ManyToOneRel" to="orm.release" name="release"&gt;2&lt;/field&gt;
557 { 470 &lt;field type="CharField" name="branch"&gt;HEAD&lt;/field&gt;
558 "name": "fido", 471 &lt;field type="CharField" name="commit"&gt;HEAD&lt;/field&gt;
559 "description": "Yocto Project 1.8 Fido", 472 &lt;field type="CharField" name="dirpath"&gt;meta&lt;/field&gt;
560 "bitbake": "fido", 473 &lt;/object&gt;
561 "branch": "fido", 474 &lt;object model="orm.layer_version" pk="3"&gt;
562 "defaultlayers": [ "openembedded-core", "meta-poky", "meta-yocto-bsp"], 475 &lt;field rel="ManyToOneRel" to="orm.layer" name="layer"&gt;1&lt;/field&gt;
563 "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 }, 476 &lt;field type="IntegerField" name="layer_source"&gt;0&lt;/field&gt;
564 "helptext": "Toaster will run your builds with the tip of the &lt;a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=fido\"&gt;Yocto Project 1.8 \"Fido\"&lt;/a&gt; branch." 477 &lt;field rel="ManyToOneRel" to="orm.release" name="release"&gt;3&lt;/field&gt;
565 }, 478
566 { 479 &lt;field type="CharField" name="branch"&gt;master&lt;/field&gt;
567 "name": "local", 480 &lt;field type="CharField" name="dirpath"&gt;meta&lt;/field&gt;
568 "description": "Local Yocto Project", 481 &lt;/object&gt;
569 "bitbake": "HEAD",
570 "branch": "HEAD",
571 "defaultlayers": [ "openembedded-core", "meta-poky", "meta-yocto-bsp"],
572 "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 },
573 "helptext": "Toaster will run your builds with the version of the Yocto Project you have cloned or downloaded to your computer."
574 }
575 ]
576 </literallayout> 482 </literallayout>
483 The layer "pk" values above must be unique, and typically start at "1".
484 The layer version "pk" values must also be unique across all layers,
485 and typically start at "1".
577 </para> 486 </para>
578 </section> 487 </section>
579 </section> 488 </section>
580 </section> 489 </section>
581
582 490
583 <section id='remote-toaster-monitoring'> 491 <section id='remote-toaster-monitoring'>
584 <title>Remote Toaster Monitoring</title> 492 <title>Remote Toaster Monitoring</title>
diff --git a/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
index 62a0b63dd7..dc2a771a3d 100644
--- a/documentation/toaster-manual/toaster-manual-setup-and-use.xml
+++ b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
@@ -382,10 +382,10 @@
382 <filename>TOASTER_CONF</filename>, which is 382 <filename>TOASTER_CONF</filename>, which is
383 relative to the Toaster root directory 383 relative to the Toaster root directory
384 <filename>TOASTER_DIR</filename>. 384 <filename>TOASTER_DIR</filename>.
385 For more information on the Toaster configuration file 385 For more information on the Toaster configuration file,
386 <filename>TOASTER_CONF</filename>, see the 386 see the
387 <link linkend='toaster-json-files'>JSON Files</link> 387 <link linkend='configuring-toaster'>Configuring Toaster</link>
388 section of this manual. 388 chapter.
389 </para> 389 </para>
390 390
391 <para> 391 <para>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-12-15 11:02:21 +0000