diff options
-rw-r--r-- | documentation/toaster-manual/toaster-manual-reference.xml | 446 | ||||
-rw-r--r-- | documentation/toaster-manual/toaster-manual-setup-and-use.xml | 8 |
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 @@ </section> </section> - <section id='toaster-json-files'> - <title>JSON Files</title> + <section id='configuring-toaster'> + <title>Configuring Toaster</title> <para> - 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. </para> -<!-- - <para> - To make it easier to initially start Toaster, you can import a - pre-defined configuration file using the - <link linkend='toaster-command-loadconf'><filename>loadconf</filename></link> - command. - <note> - The configuration file is a JSON-formatted text file with - specific fields that Toaster recognizes. - It is not a data dump from the database, so it cannot be - loaded directly in the database. - </note> - </para> ---> - - <para> - By convention, the supplied configuration files are named - <filename>toasterconf.json</filename>. - The Toaster Administrator can customize the file prior to loading - it into Toaster. - The <filename>TOASTER_CONF</filename> variable in the - Toaster startup script at <filename>bitbake/bin/toaster</filename> - specifies the location of the <filename>toasterconf.json</filename> file. - </para> - - <section id='json-file-choices'> - <title>Configuration File Choices</title> + <section id='configuring-the-workflow'> + <title>Configuring the Workflow</title> <para> - Two versions of the configuration file exist: - <itemizedlist> + The + <filename>bldcontrol/management/commands/checksettings.py</filename> + file controls workflow configuration. + The following steps outline the process to initially populate + this database. + <orderedlist> <listitem><para> - The - <filename>meta-poky/conf/toasterconf.json</filename> - in the <filename>conf</filename> directory of the - Yocto Project's <filename>meta-poky</filename> 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 - <filename>poky</filename> repository (i.e. - <filename>&YOCTO_GIT_URL;/poky</filename>). + The default project settings are set from + <filename>orm/fixtures/settings.xml</filename>. </para></listitem> <listitem><para> - The <filename>meta/conf/toasterconf.json</filename> - in the <filename>conf</filename> directory of the - OpenEmbedded's <filename>openembedded-core</filename> - 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 - <filename>openembedded-core</filename> repository (i.e. - <filename>git://git.openembedded.org/openembedded-core</filename>). + The default project distro and layers are added + from <filename>orm/fixtures/poky.xml</filename> if poky + is installed. + If poky is not installed, they are added + from <filename>orm/fixtures/oe-core.xml</filename>. </para></listitem> - </itemizedlist> + <listitem><para> + If the <filename>orm/fixtures/custom.xml</filename> file + exists, then its values are added. + </para></listitem> + <listitem><para> + The layer index is then scanned and added to the database. + </para></listitem> + </orderedlist> + Once these steps complete, Toaster is set up and ready to use. </para> </section> - <section id='json-structure'> - <title>File Structure</title> + <section id='customizing-pre-set-data'> + <title>Customizing Pre-Set Data</title> <para> - The <filename>toasterconf.json</filename> 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 <filename>orm/fixtures/custom.xml</filename> file + to customize the values that go into to the database. + Customization is additive, + and can either extend or completely replace the existing values. </para> - <section id='json-config-area'> - <title>Configuration Area</title> + <para> + You use the <filename>orm/fixtures/custom.xml</filename> 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 + <filename>oe-core.xml</filename> and <filename>poky.xml</filename> + files by defining the section shown below in the + <filename>settings.xml</filename> file. + For example, this option is particularly useful if your custom + configuration defines fewer releases or layers than the default + fixture files. + </para> - <para> - This area of the JSON file sets which variables are exposed - to users through the Toaster web interface. - Users can easily edit these variables. - </para> + <para> + The following example sets "name" to "CUSTOM_XML_ONLY" and its value + to "True". + <literallayout class='monospaced'> + <object model="orm.toastersetting" pk="99"> + <field type="CharField" name="name">CUSTOM_XML_ONLY</field> - <para> - The variables you set here are displayed in the - "Configuration variables" page in Toaster. - Minimally, you should set the - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - variable, which appears to users as part of the project - page in Toaster. - </para> + <field type="CharField" name="value">True</field> + </object> + </literallayout> + </para> + </section> - <para> - Here is the default <filename>config</filename> area: - <literallayout class='monospaced'> - "config": { - "MACHINE" : "qemux86", - "DISTRO" : "poky", - "IMAGE_FSTYPES": "ext3 jffs2 tar.bz2", - "IMAGE_INSTALL_append": "", - "PACKAGE_CLASSES": "package_rpm", - }, - </literallayout> - </para> - </section> + <section id='understanding-fixture-file-format'> + <title>Understanding Fixture File Format</title> - <section id='json-layersources-area'> - <title>Layer Sources Area</title> + <para> + The following is an overview of the file format used by the + <filename>oe-core.xml</filename>, <filename>poky.xml</filename>, + and <filename>custom.xml</filename> files. + </para> - <para> - This area of the JSON file defines the - <link linkend='layer-source'>layer sources</link> - Toaster uses. - Toaster reads layer information from layer sources. - Three types of layer sources exist that Toaster - recognizes: Local, LayerIndex, and Imported. - </para> + <para> + 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 + <filename>custom.xml</filename> file. + </para> + + <section id='defining-the-default-distro'> + <title>Defining the Default Distro</title> <para> - 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 + <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>: + <literallayout class='monospaced'> + <!-- 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> + </literallayout> <note> - 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 <filename>settings.xml</filename> 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. </note> </para> + </section> - <para> - The LayerIndex layer source uses a REST API exposed by - instances of the Layer Index application (e.g the public - <ulink url='http://layers.openembedded.org/'></ulink>) - to read layer data. - </para> - - <para> - 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. - </para> + <section id='defining-bitbake-version'> + <title>Defining BitBake Version</title> <para> - Here is the default <filename>layersources</filename> area: + The following defines which version of BitBake is used + for the following release selection: <literallayout class='monospaced'> - "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> </literallayout> </para> </section> - <section id='json-bitbake-area'> - <title>BitBake Area</title> - - <para> - 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. - <note> - HEAD is a special option that builds whatever is - available on disk, without checking out any remote - Git repositories. - </note> - </para> + <section id='defining-releases'> + <title>Defining Release</title> <para> - Here is the default <filename>bitbake</filename> area: + The following defines the releases when you create a new + project. <literallayout class='monospaced'> - "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> </literallayout> + The "pk" value must match the above respective BitBake + version record. </para> </section> - <section id='json-default-area'> - <title>Default Area</title> + <section id='defining-the-release-default-layer-names'> + <title>Defining the Release Default Layer Names</title> <para> - This area of the JSON file establishes a default - release used by Toaster. - As shipped, Toaster uses the "master" release. - </para> - - <para> - Here is the statement in the JSON file that establishes - the default release: + The following defines the default layers for each release: <literallayout class='monospaced'> - "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> </literallayout> + The 'pk' values in the example above should start at "1" and increment + uniquely. + You can use the same layer name in multiple releases. </para> </section> - <section id='json-releases-area'> - <title>Releases Area</title> + <section id='defining-layer-definitions'> + <title>Defining Layer Definitions</title> <para> - 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 - "<link linkend='toaster-releases-supported'>Pre-Configured Releases</link>" - section. - </para> - - <para> - Here is the default <filename>releases</filename> 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. <literallayout class='monospaced'> - "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> </literallayout> + 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". </para> </section> </section> - </section> - + </section> <section id='remote-toaster-monitoring'> <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 @@ <filename>TOASTER_CONF</filename>, which is relative to the Toaster root directory <filename>TOASTER_DIR</filename>. - For more information on the Toaster configuration file - <filename>TOASTER_CONF</filename>, see the - <link linkend='toaster-json-files'>JSON Files</link> - section of this manual. + For more information on the Toaster configuration file, + see the + <link linkend='configuring-toaster'>Configuring Toaster</link> + chapter. </para> <para> |