From 285c92aef900128b9564c353470d4579b1e1f0f8 Mon Sep 17 00:00:00 2001 From: Kristi Rifenbark Date: Fri, 13 Oct 2017 10:16:14 -0700 Subject: toaster-manual: Created "Configuring Toaster" chapter Deleted the existing JSON chapter, and replaced it with this new chapter. (From yocto-docs rev: 86f9fb9c567310ecd1b06944c4c9107ec30df29c) Signed-off-by: Kristi Rifenbark Signed-off-by: Richard Purdie --- .../toaster-manual/toaster-manual-reference.xml | 446 ++++++++------------- .../toaster-manual-setup-and-use.xml | 8 +- 2 files changed, 181 insertions(+), 273 deletions(-) (limited to 'documentation') 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 @@ -
- JSON Files +
+ Configuring Toaster - You must configure Toaster before using it. - Configuration customizes layer source settings and Toaster defaults - for all users and is performed by the person responsible for - Toaster Configuration (i.e the Toaster Administrator). - The Toaster Administrator performs this configuration through the - Django administration interface. + In order to use Toaster, you must configure the database with the + default content. The following subsections describe various aspects + of Toaster configuration. - - - - By convention, the supplied configuration files are named - toasterconf.json. - The Toaster Administrator can customize the file prior to loading - it into Toaster. - The TOASTER_CONF variable in the - Toaster startup script at bitbake/bin/toaster - specifies the location of the toasterconf.json file. - - -
- Configuration File Choices +
+ Configuring the Workflow - Two versions of the configuration file exist: - + The + bldcontrol/management/commands/checksettings.py + file controls workflow configuration. + The following steps outline the process to initially populate + this database. + - The - meta-poky/conf/toasterconf.json - in the conf directory of the - Yocto Project's meta-poky layer. - This version contains the default Yocto Project - configuration for Toaster. - You are prompted to select this file during the Toaster - set up process if you cloned the - poky repository (i.e. - &YOCTO_GIT_URL;/poky). + The default project settings are set from + orm/fixtures/settings.xml. - The meta/conf/toasterconf.json - in the conf directory of the - OpenEmbedded's openembedded-core - layer. - This version contains the default OpenEmbedded - configuration for Toaster. - You are prompted to select this file during the Toaster - set up process if you had cloned the - openembedded-core repository (i.e. - git://git.openembedded.org/openembedded-core). + The default project distro and layers are added + from orm/fixtures/poky.xml if poky + is installed. + If poky is not installed, they are added + from orm/fixtures/oe-core.xml. - + + If the orm/fixtures/custom.xml file + exists, then its values are added. + + + The layer index is then scanned and added to the database. + + + Once these steps complete, Toaster is set up and ready to use.
-
- File Structure +
+ Customizing Pre-Set Data - The toasterconf.json file consists of - easily readable areas: configuration, layer sources, BitBake, - default release, and releases. + The pre-set data for Toaster is easily customizable. You can + create the orm/fixtures/custom.xml file + to customize the values that go into to the database. + Customization is additive, + and can either extend or completely replace the existing values. -
- Configuration Area + + You use the orm/fixtures/custom.xml file + to change the default project settings for the machine, distro, + file images, and layers. + When creating a new project, you can use the file to define + the offered alternate project release selections. + For example, you can add one or more additional selections that + present custom layer sets or distros, and any other local or proprietary + content. + Additionally, you can completely disable the content from the + oe-core.xml and poky.xml + files by defining the section shown below in the + settings.xml file. + For example, this option is particularly useful if your custom + configuration defines fewer releases or layers than the default + fixture files. + - - This area of the JSON file sets which variables are exposed - to users through the Toaster web interface. - Users can easily edit these variables. - + + The following example sets "name" to "CUSTOM_XML_ONLY" and its value + to "True". + + <object model="orm.toastersetting" pk="99"> + <field type="CharField" name="name">CUSTOM_XML_ONLY</field> - - The variables you set here are displayed in the - "Configuration variables" page in Toaster. - Minimally, you should set the - MACHINE - variable, which appears to users as part of the project - page in Toaster. - + <field type="CharField" name="value">True</field> + </object> + + +
- - Here is the default config area: - - "config": { - "MACHINE" : "qemux86", - "DISTRO" : "poky", - "IMAGE_FSTYPES": "ext3 jffs2 tar.bz2", - "IMAGE_INSTALL_append": "", - "PACKAGE_CLASSES": "package_rpm", - }, - - -
+
+ Understanding Fixture File Format -
- Layer Sources Area + + The following is an overview of the file format used by the + oe-core.xml, poky.xml, + and custom.xml files. + - - This area of the JSON file defines the - layer sources - Toaster uses. - Toaster reads layer information from layer sources. - Three types of layer sources exist that Toaster - recognizes: Local, LayerIndex, and Imported. - + + The following subsections describe each of the sections in the + fixture files, and outline an example section of the XML code. + you can use to help understand this information and create a local + custom.xml file. + + +
+ Defining the Default Distro - The Local layer source reads layers from Git clones - available on your local drive. - Using a local layer source enables you to easily test - Toaster. + This section defines the default distro value for new projects. + By default, it reserves the first Toaster Setting record "1". + The following demonstrates how to set the project default value + for + DISTRO: + + <!-- Set the project default value for DISTRO --> + <object model="orm.toastersetting" pk="1"> + <field type="CharField" name="name">DEFCONF_DISTRO</field> + <field type="CharField" name="value">poky</field> + </object> + - If you are setting up a hosted version of Toaster, - it does not make sense to have a local layer source. + You can override the default value by adding additional + Toaster Setting sections such as any of the settings coming + from the settings.xml file. + Also, you can add custom values that are included in the + BitBake environment. + The "pk" values must be unique. + By convention, values that set default project values have a + "DEFCONF" prefix. +
- - The LayerIndex layer source uses a REST API exposed by - instances of the Layer Index application (e.g the public - ) - to read layer data. - - - - The Imported layer source is reserved for layer data - manually introduced by the user or Toaster Administrator - through the GUI. - This layer source lets users import their own layers - and build them with Toaster. - You should not remove the imported layer source. - +
+ Defining BitBake Version - Here is the default layersources area: + The following defines which version of BitBake is used + for the following release selection: - "layersources": [ - { - "name": "Local Yocto Project", - "sourcetype": "local", - "apiurl": "../../", - "branches": ["HEAD" ], - "layers": [ - { - "name": "openembedded-core", - "local_path": "meta", - "vcs_url": "remote:origin", - "dirpath": "meta" - }, - { - "name": "meta-poky", - "local_path": "meta-poky", - "vcs_url": "remote:origin", - "dirpath": "meta-poky" - }, - { - "name": "meta-yocto-bsp", - "local_path": "meta-yocto-bsp", - "vcs_url": "remote:origin", - "dirpath": "meta-yocto-bsp" - } - - ] - }, - { - "name": "OpenEmbedded", - "sourcetype": "layerindex", - "apiurl": "http://layers.openembedded.org/layerindex/api/", - "branches": ["master", "jethro" ,"fido"] - }, - { - "name": "Imported layers", - "sourcetype": "imported", - "apiurl": "", - "branches": ["master", "jethro","fido", "HEAD"] - - } - ], + <!-- Bitbake versions which correspond to the metadata release --> + <object model="orm.bitbakeversion" pk="1"> + <field type="CharField" name="name">rocko</field> + <field type="CharField" name="giturl">git://git.yoctoproject.org/poky</field> + <field type="CharField" name="branch">rocko</field> + <field type="CharField" name="dirpath">bitbake</field> + </object>
-
- BitBake Area - - - This area of the JSON file defines the version of - BitBake Toaster uses. - As shipped, Toaster is configured to recognize four - versions of BitBake: master, fido, jethro, and HEAD. - - HEAD is a special option that builds whatever is - available on disk, without checking out any remote - Git repositories. - - +
+ Defining Release - Here is the default bitbake area: + The following defines the releases when you create a new + project. - "bitbake" : [ - { - "name": "master", - "giturl": "remote:origin", - "branch": "master", - "dirpath": "bitbake" - }, - { - "name": "jethro", - "giturl": "remote:origin", - "branch": "jethro", - "dirpath": "bitbake" - }, - { - "name": "fido", - "giturl": "remote:origin", - "branch": "fido", - "dirpath": "bitbake" - }, - { - "name": "HEAD", - "giturl": "remote:origin", - "branch": "HEAD", - "dirpath": "bitbake" - } - ], + <!-- Releases available --> + <object model="orm.release" pk="1"> + <field type="CharField" name="name">rocko</field> + <field type="CharField" name="description">Yocto Project 2.4 "Rocko"</field> + <field rel="ManyToOneRel" to="orm.bitbakeversion" name="bitbake_version">1</field> + <field type="CharField" name="branch_name">rocko</field> + <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=rocko">Yocto Project Rocko branch</a>.</field> + </object> + The "pk" value must match the above respective BitBake + version record.
-
- Default Area +
+ Defining the Release Default Layer Names - This area of the JSON file establishes a default - release used by Toaster. - As shipped, Toaster uses the "master" release. - - - - Here is the statement in the JSON file that establishes - the default release: + The following defines the default layers for each release: - "defaultrelease": "master", + <!-- Default project layers for each release --> + <object model="orm.releasedefaultlayer" pk="1"> + <field rel="ManyToOneRel" to="orm.release" name="release">1</field> + <field type="CharField" name="layer_name">openembedded-core</field> + </object> + The 'pk' values in the example above should start at "1" and increment + uniquely. + You can use the same layer name in multiple releases.
-
- Releases Area +
+ Defining Layer Definitions - This area of the JSON file defines the versions of the - OpenEmbedded build system Toaster recognizes. - As shipped, Toaster is configured to work with the four - releases described in the - "Pre-Configured Releases" - section. - - - - Here is the default releases area: + Layer definitions are the most complex. + The following defines each of the layers, and then defines the exact layer + version of the layer used for each respective release. - "releases": [ - { - "name": "master", - "description": "Yocto Project master", - "bitbake": "master", - "branch": "master", - "defaultlayers": [ "openembedded-core", "meta-poky", "meta-yocto-bsp"], - "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 }, - "helptext": "Toaster will run your builds using the tip of the <a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/\">Yocto Project master branch</a>, where active development takes place. This is not a stable branch, so your builds might not work as expected." - }, - { - "name": "jethro", - "description": "Yocto Project 2.0 Jethro", - "bitbake": "jethro", - "branch": "jethro", - "defaultlayers": [ "openembedded-core", "meta-poky", "meta-yocto-bsp"], - "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 }, - "helptext": "Toaster will run your builds with the tip of the <a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=jethro\">Yocto Project 2.0 \"Jethro\"</a> branch." - }, - { - "name": "fido", - "description": "Yocto Project 1.8 Fido", - "bitbake": "fido", - "branch": "fido", - "defaultlayers": [ "openembedded-core", "meta-poky", "meta-yocto-bsp"], - "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 }, - "helptext": "Toaster will run your builds with the tip of the <a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=fido\">Yocto Project 1.8 \"Fido\"</a> branch." - }, - { - "name": "local", - "description": "Local Yocto Project", - "bitbake": "HEAD", - "branch": "HEAD", - "defaultlayers": [ "openembedded-core", "meta-poky", "meta-yocto-bsp"], - "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 }, - "helptext": "Toaster will run your builds with the version of the Yocto Project you have cloned or downloaded to your computer." - } - ] + <object model="orm.layer" pk="1"> + <field type="CharField" name="name">openembedded-core</field> + <field type="CharField" name="layer_index_url"></field> + <field type="CharField" name="vcs_url">git://git.yoctoproject.org/poky</field> + <field type="CharField" name="vcs_web_url">http://git.yoctoproject.org/cgit/cgit.cgi/poky</field> + <field type="CharField" name="vcs_web_tree_base_url">http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%</field> + <field type="CharField" name="vcs_web_file_base_url">http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%</field> + </object> + <object model="orm.layer_version" pk="1"> + <field rel="ManyToOneRel" to="orm.layer" name="layer">1</field> + <field type="IntegerField" name="layer_source">0</field> + <field rel="ManyToOneRel" to="orm.release" name="release">1</field> + <field type="CharField" name="branch">rocko</field> + <field type="CharField" name="dirpath">meta</field> + </object> + <object model="orm.layer_version" pk="2"> + <field rel="ManyToOneRel" to="orm.layer" name="layer">1</field> + <field type="IntegerField" name="layer_source">0</field> + <field rel="ManyToOneRel" to="orm.release" name="release">2</field> + <field type="CharField" name="branch">HEAD</field> + <field type="CharField" name="commit">HEAD</field> + <field type="CharField" name="dirpath">meta</field> + </object> + <object model="orm.layer_version" pk="3"> + <field rel="ManyToOneRel" to="orm.layer" name="layer">1</field> + <field type="IntegerField" name="layer_source">0</field> + <field rel="ManyToOneRel" to="orm.release" name="release">3</field> + + <field type="CharField" name="branch">master</field> + <field type="CharField" name="dirpath">meta</field> + </object> + The layer "pk" values above must be unique, and typically start at "1". + The layer version "pk" values must also be unique across all layers, + and typically start at "1".
-
- +
Remote Toaster Monitoring 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 @@ TOASTER_CONF, which is relative to the Toaster root directory TOASTER_DIR. - For more information on the Toaster configuration file - TOASTER_CONF, see the - JSON Files - section of this manual. + For more information on the Toaster configuration file, + see the + Configuring Toaster + chapter. -- cgit v1.2.3-54-g00ecf