diff options
| author | Brad Bishop <bradleyb@fuzziesquirrel.com> | 2018-02-26 06:55:05 +0300 |
|---|---|---|
| committer | Brad Bishop <bradleyb@fuzziesquirrel.com> | 2018-03-15 17:22:49 +0300 |
| commit | d7bf8c17eca8f8c89898a7794462c773c449e983 (patch) | |
| tree | d18618fca85ca5f0c077032cc7b009344b60f663 /import-layers/yocto-poky/documentation/toaster-manual | |
| parent | e2b5abdc9f28cdf8578e5b9be803c8e697443c20 (diff) | |
| download | openbmc-d7bf8c17eca8f8c89898a7794462c773c449e983.tar.xz | |
Yocto 2.4
Move OpenBMC to Yocto 2.4(rocko)
Tested: Built and verified Witherspoon and Palmetto images
Change-Id: I12057b18610d6fb0e6903c60213690301e9b0c67
Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>
Diffstat (limited to 'import-layers/yocto-poky/documentation/toaster-manual')
5 files changed, 441 insertions, 648 deletions
diff --git a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-intro.xml b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-intro.xml index a408024d8..4e59e0078 100644 --- a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-intro.xml +++ b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-intro.xml @@ -7,7 +7,7 @@ <para> Toaster is a web interface to the Yocto Project's - <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>. + <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>. The interface enables you to configure and run your builds. Information about builds is collected and stored in a database. You can use Toaster to configure and start builds on multiple diff --git a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-reference.xml b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-reference.xml index 3a46b61b7..e984391fd 100644 --- a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-reference.xml +++ b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-reference.xml @@ -148,177 +148,46 @@ </para> </section> - <section id='select-the-toasterconf-json-file'> - <title>Use the <filename>toasterconf.json</filename> File</title> + <section id='use-the-fixture-feature'> + <title>Use the Fixture Feature</title> <para> - If you do not want to use the Administration - Interface, you can edit the - <link linkend='toaster-json-files'><filename>toasterconf.json</filename></link> - file and reload it to Toaster. - </para> - - <para> - The Toaster startup script in - <filename>/bitbake/bin/toaster</filename> specifies - the location of a Toaster configuration file - <filename>toasterconf.json</filename> as the value of - the <filename>TOASTER_CONF</filename> variable. - This configuration file is used to set up the initial - configuration values within the Toaster database - including the layer sources. - Two versions of the configuration file exist: - <itemizedlist> - <listitem><para> - The first version of the file is found in the - <filename>conf</filename> directory of the - <filename>meta-poky</filename> layer - (i.e. - <filename>meta-poky/conf/toasterconf.json</filename>). - This version contains the default Yocto Project - configuration for Toaster. - </para></listitem> - <listitem><para> - The second version of the file is in the - <filename>conf</filename> directory of the - <filename>openembedded-core</filename> layer - (i.e. <filename>meta/conf/toasterconf.json</filename>). - This version contains the default OpenEmbedded - configuration for Toaster. - </para></listitem> - </itemizedlist> - </para> - </section> - - <section id='edit-the-configuration-file'> - <title>Edit the Configuration File</title> - - <para> - Edit the version of the - <filename>toasterconf.json</filename> file you - used to set up your Toaster instance. - In the file, you will find a section for layer sources - such as the following: + The Django fixture feature overrides the default layer + server when you use it to specify a custom URL. To use + the fixture feature, create (or edit) the file + <filename>bitbake/lib/toaster.orm/fixtures/custom.xml</filename>, + and then set the following Toaster setting to your + custom URL: <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"] - - } - ], + <?xml version="1.0" ?> + <django-objects version="1.0"> + <object model="orm.toastersetting" pk="100"> + <field name="name" type="CharField">CUSTOM_LAYERINDEX_SERVER</field> + <field name="value" type="CharField">https://layers.my_organization.org/layerindex/branch/master/layers/</field> + </object> + <django-objects> </literallayout> - You should add your own layer source to this section by - following the same format used for the "OpenEmbedded" - layer source shown above. + When you start Toaster for the first time, or if you + delete the file <filename>toaster.sqlite</filename> and restart, + the database will populate cleanly from this layer index server. </para> <para> - Give your layer source a name, provide the URL of your - layer source API, use the source type "layerindex", and - indicate which branches from your layer source you want - to make available through Toaster. - For example, the OpenEmbedded layer source makes - available only its "master", "fido", and "jethro" - branches. - </para> - - <para> - The branches must match the branch you - set when configuring your releases. - For example, if you configure one release in Toaster - by setting its branch to "branch-one" and you configure - another release in Toaster by setting its branch to - "branch-two", the branches in your layer source should - be "branch-one" and "branch-two" as well. - Doing so creates a connection between the releases - and the layer information from your layer source. - Thus, when users create a project with a given - release, they will see the appropriate layers from - your layer source. - This connection ensures that only layers that are - compatible with the selected project release can be - selected for building. - </para> - - <para> - Once you have added this information to the - <filename>toasterconf.json</filename> file, save your - changes. + Once the information has been updated, verify the new layer + information is available by using the Toaster web interface. + To do that, visit the "All compatible layers" page inside a + Toaster project. The layers from your layer source should be + listed there. </para> <para> - In a terminal window, navigate to the directory that - contains the Toaster database, which by default is the - root of the Yocto Project - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. - Once you are located in that directory, run the - "<filename>loadconf</filename>" command, which takes as - an argument the full path to the - <filename>toasterconf.json</filename> file you just edited. - For example, if you cloned the - <filename>poky</filename> repository and you edited the - <filename>meta-poky/conf/toasterconf.json</filename> file, - you would type something like the following: - <literallayout class='monospaced'> - $ bitbake/lib/toaster/manage.py loadconf /home/scottrif/poky/meta-poky/conf/toasterconf.json - </literallayout> - After entering this command, you need to update the - Toaster database with the information coming from your - new layer source. - To do that, you should run the - "<filename>lsupdates</filename>" command from the directory - that contains the Toaster database. - Here is an example: + If you change the information in your layer index server, + refresh the Toaster database by running the following command: <literallayout class='monospaced'> $ bitbake/lib/toaster/manage.py lsupdates </literallayout> If Toaster can reach the API URL, you should see a message - telling you that Toaster is updating the layer source - information. - </para> - - <para> - Once the information has been updated, verify the new layer - information is available by using the Toaster web interface. - To do that, visit the "All compatible layers" page inside a - Toaster project. - The layers from your layer source should be listed there. + telling you that Toaster is updating the layer source information. </para> </section> </section> @@ -359,19 +228,12 @@ As shipped, Toaster is configured to work with the following releases: <itemizedlist> - <listitem><para><emphasis>Yocto Project 2.0 "Jethro" or OpenEmbedded "Jethro":</emphasis> - This release causes your Toaster projects to - build against the head of the jethro branch at - <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/?h=jethro'></ulink> - or - <ulink url='http://git.openembedded.org/openembedded-core/commit/?h=jethro'></ulink>. - </para></listitem> - <listitem><para><emphasis>Yocto Project 1.8 "Fido" or OpenEmbedded "Fido":</emphasis> - This release causes your Toaster projects to - build against the head of the fido branch at - <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/?h=fido'></ulink> - or - <ulink url='http://git.openembedded.org/openembedded-core/commit/?h=fido'></ulink>. + <listitem><para><emphasis> + Yocto Project &DISTRO; "&DISTRO_NAME;" or OpenEmbedded "&DISTRO_NAME;":</emphasis> + This release causes your Toaster projects to build + against the head of the &DISTRO_NAME_NO_CAP; branch at + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/?h=rocko'></ulink> + or <ulink url='http://git.openembedded.org/openembedded-core/commit/?h=rocko'></ulink>. </para></listitem> <listitem><para><emphasis>Yocto Project "Master" or OpenEmbedded "Master":</emphasis> This release causes your Toaster Projects to @@ -390,471 +252,416 @@ </itemizedlist> </para> </section> + </section> + + <section id='configuring-toaster'> + <title>Configuring Toaster</title> + + <para> + In order to use Toaster, you must configure the database with the + default content. The following subsections describe various aspects + of Toaster configuration. + </para> - <section id='toaster-releases-comprised-of'> - <title>What Makes Up a Release?</title> + <section id='configuring-the-workflow'> + <title>Configuring the Workflow</title> <para> - A release consists of the following: - <itemizedlist> - <listitem><para><emphasis>Name:</emphasis> - The name of the release (<filename>name</filename>). - This release name never appears in the the Toaster - web interface. - Consequently, a user never sees the release name. - </para></listitem> - <listitem><para><emphasis>Description:</emphasis> - The textual description of the release - (<filename>description</filename>). - This description is what users encounter when creating - projects with the Toaster web interface. - When you configure your release, be sure to use - a description that sufficiently describes and is - understandable. - If Toaster has more than one release configured, the - release descriptions appear listed in a drop down menu - when a user creates a new project. - If Toaster has only one release configured, all - projects created using the web interface take that - release and the drop down menu does not display in the - Toaster web interface. - </para></listitem> - <listitem><para><emphasis>BitBake:</emphasis> - The Bitbake version (<filename>bitbake</filename>) - used to build layers set in the current release. - This version is described by a name, a Git URL, a - branch in the Git URL, and a directory path in the - Git repository. - As an example, consider the following snippet from - a Toaster JSON configuration file. - This BitBake version uses the master branch from the - OpenEmbedded repository: - <literallayout class='monospaced'> - "bitbake" : [ - { - "name": "master", - "giturl": "git://git.openembedded.org/bitbake", - "branch": "master", - "dirpath": "" - } - ] - </literallayout> - Here is more detail on each of the items that comprise - the BitBake version: - <itemizedlist> - <listitem><para><emphasis>Name:</emphasis> - A string - (<filename>name</filename>) used to refer to - the version of BitBake you are using with - Toaster. - This name is never exposed through Toaster. - </para></listitem> - <listitem><para><emphasis>Git URL:</emphasis> - The URL (<filename>giturl</filename>) - for the BitBake Git repository cloned - for Toaster projects. - </para></listitem> - <listitem><para><emphasis>Branch:</emphasis> - The Git branch, or revision, - (<filename>branch</filename>) of the BitBake - repository used with Toaster. - </para></listitem> - <listitem><para><emphasis>Directory Path:</emphasis> - The sub-directory of the BitBake repository - (<filename>dirpath</filename>). - If the Git URL includes more than one - repository, you need to set this directory. - If the URL does not include more than a single - repository, you can set - <filename>dirpath</filename> to a null string - (i.e. ""). - </para></listitem> - </itemizedlist> - </para></listitem> - <listitem><para><emphasis>Branch:</emphasis> - The branch for the layer source - (<filename>branch</filename>) used with the release. - For example, for the OpenEmbedded layer source, the - "master", "fido", and "jethro" branches are available. + 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 default project settings are set from + <filename>orm/fixtures/settings.xml</filename>. </para></listitem> - <listitem><para><emphasis>Default Layers:</emphasis> - The set of default layers - (<filename>defaultlayers</filename>) automatically - added to the project configuration when a project is - created. + <listitem><para> + 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> - <listitem><para><emphasis>Layer Source Priorities</emphasis> - A specification of - <link linkend='layer-source'>layer source</link> - priorities (<filename>layersourcepriority</filename>). - In order for Toaster to work as intended, the - "Imported layers" layer source should have the highest - priority, which means that layers manually imported by - users with the "Import layer" functionality will - always be visible and available for selection. + <listitem><para> + If the <filename>orm/fixtures/custom.xml</filename> file + exists, then its values are added. </para></listitem> - <listitem><para><emphasis>Help Text:</emphasis> - Help text (<filename>helptext</filename>) that explains - what the release does when selected. - This help text appears below the release drop-down - menu when you create a Toaster project. - The help text should assist users in making the correct - decision regarding the release to use for a given - project. + <listitem><para> + The layer index is then scanned and added to the database. </para></listitem> - </itemizedlist> - </para> - - <para> - To summarize what comprises a release, consider the following - example from a Toaster JSON file. - The configuration names the release "master" and uses the - "master" branch provided by the layer source of type - "layerindex", which is called "OpenEmbedded", and sets - the <filename>openembedded-core</filename> layer as the one - to be added by default to any projects created in Toaster. - The BitBake version used would be defined as shown earlier - in the previous list: - <literallayout class='monospaced'> - "releases": [ - { - "name": "master", - "description": "OpenEmbedded master", - "bitbake": "master", - "branch": "master", - "defaultlayers": [ "openembedded-core" ], - "layersourcepriority": { "Imported layers": 99, "Local OpenEmbedded" : 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." - } - ] - </literallayout> + </orderedlist> + Once these steps complete, Toaster is set up and ready to use. </para> </section> - </section> - - <section id='toaster-json-files'> - <title>JSON Files</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. - </para> + <section id='customizing-pre-set-data'> + <title>Customizing Pre-Set Data</title> - <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> + 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> - <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> + <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. + </para> - <section id='json-file-choices'> - <title>Configuration File Choices</title> + <para> + 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> - Two versions of the configuration file exist: - <itemizedlist> - <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>). - </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>). - </para></listitem> - </itemizedlist> + 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> + <field type="CharField" name="value">True</field> + </object> + </literallayout> </para> </section> - <section id='json-structure'> - <title>File Structure</title> + <section id='understanding-fixture-file-format'> + <title>Understanding Fixture File Format</title> <para> - The <filename>toasterconf.json</filename> file consists of - easily readable areas: configuration, layer sources, BitBake, - default release, and releases. + 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> - <section id='json-config-area'> - <title>Configuration Area</title> + <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> - <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> + <section id='defining-the-default-distro-and-other-values'> + <title>Defining the Default Distro and Other Values</title> <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> - - <para> - Here is the default <filename>config</filename> area: + 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'> - "config": { - "MACHINE" : "qemux86", - "DISTRO" : "poky", - "IMAGE_FSTYPES": "ext3 jffs2 tar.bz2", - "IMAGE_INSTALL_append": "", - "PACKAGE_CLASSES": "package_rpm", - }, + <!-- 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> + You can override other default project values 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. </para> </section> - <section id='json-layersources-area'> - <title>Layer Sources Area</title> - - <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 Local layer source reads layers from Git clones - available on your local drive. - Using a local layer source enables you to easily test - Toaster. - <note> - If you are setting up a hosted version of Toaster, - it does not make sense to have a local layer source. - </note> - </para> - - <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> + <section id='defining-releases'> + <title>Defining Release</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> - - <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> - - <para> - This area of the JSON file establishes a default - release used by Toaster. - As shipped, Toaster uses the "master" release. - </para> + <section id='defining-the-release-default-layer-names'> + <title>Defining the Release Default Layer Names</title> <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> - - <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> + <section id='defining-layer-definitions'> + <title>Defining Layer Definitions</title> <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. + You must have one <filename>orm.layer</filename> + entry for each layer. + Then, with each entry you need a set of + <filename>orm.layer_version</filename> entries that connects + the layer with each release that includes the layer. + In general all releases include the layer. <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 id='remote-toaster-monitoring'> + <title>Remote Toaster Monitoring</title> + + <para> + Toaster has an API that allows remote management applications to + directly query the state of the Toaster server and its builds + in a machine-to-machine manner. + This API uses the + <ulink url='http://en.wikipedia.org/wiki/Representational_state_transfer'>REST</ulink> + interface and the transfer of JSON files. + For example, you might + monitor a build inside a container through well supported + known HTTP ports in order to easily access a Toaster server + inside the container. + In this example, when you use this direct JSON API, you avoid + having web page parsing against the display the user sees. + </para> + + <section id='checking-health'> + <title>Checking Health</title> + + <para> + Before you use remote Toaster monitoring, you should do + a health check. + To do this, ping the Toaster server using the following call + to see if it is still alive: + <literallayout class='monospaced'> + http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/health + </literallayout> + Be sure to provide values for <replaceable>host</replaceable> + and <replaceable>port</replaceable>. + If the server is alive, you will get the response HTML: + <literallayout class='monospaced'> + <!DOCTYPE html> + <html lang="en"> + <head><title>Toaster Health</title></head> + <body>Ok</body> + </html> + </literallayout> + </para> + </section> + + <section id='determining-status-of-builds-in-progress'> + <title>Determining Status of Builds in Progress</title> + + <para> + Sometimes it is useful to determine the status of a build + in progress. + To get the status of pending builds, use the following call: + <literallayout class='monospaced'> + http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/toastergui/api/building + </literallayout> + Be sure to provide values for <replaceable>host</replaceable> + and <replaceable>port</replaceable>. + The output is a JSON file that itemizes all builds in + progress. + This file includes the time in seconds since each + respective build started as well as the progress of the + cloning, parsing, and task execution. + The following is sample output for a build in progress: + <literallayout class='monospaced'> + {"count": 1, + "building": [ + {"machine": "beaglebone", + "seconds": "463.869", + "task": "927:2384", + "distro": "poky", + "clone": "1:1", + "id": 2, + "start": "2017-09-22T09:31:44.887Z", + "name": "20170922093200", + "parse": "818:818", + "project": "my_rocko", + "target": "core-image-minimal" + }] + } + </literallayout> + The JSON data for this query is returned in a single line. + In the previous example the line has been artificially split for readability. + </para> + </section> + + <section id='checking-status-of-builds-completed'> + <title>Checking Status of Builds Completed</title> + + <para> + Once a build is completed, you get the status when you use + the following call: + <literallayout class='monospaced'> + http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/toastergui/api/builds + </literallayout> + Be sure to provide values for <replaceable>host</replaceable> + and <replaceable>port</replaceable>. + The output is a JSON file that itemizes all complete builds, + and includes build summary information. + The following is sample output for a completed build: + <literallayout class='monospaced'> + {"count": 1, + "builds": [ + {"distro": "poky", + "errors": 0, + "machine": + "beaglebone", + "project": "my_rocko", + "stop": "2017-09-22T09:26:36.017Z", + "target": "quilt-native", + "seconds": "78.193", + "outcome": "Succeeded", + "id": 1, + "start": "2017-09-22T09:25:17.824Z", + "warnings": 1, + "name": "20170922092618" + }] + } + </literallayout> + The JSON data for this query is returned in a single line. + In the previous example the line has been artificially split for readability. + </para> + </section> + + <section id='determining-status-of-a-specific-build'> + <title>Determining Status of a Specific Build</title> + + <para> + Sometimes it is useful to determine the status of a specific + build. + To get the status of a specific build, use the following + call: + <literallayout class='monospaced'> + http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/toastergui/api/build/<replaceable>ID</replaceable> + </literallayout> + Be sure to provide values for <replaceable>host</replaceable>, + <replaceable>port</replaceable>, and <replaceable>ID</replaceable>. + You can find the value for <replaceable>ID</replaceable> from the + Builds Completed query. See the + "<link linkend='checking-status-of-builds-completed'>Checking Status of Builds Completed</link>" + section for more information. + </para> + + <para> + The output is a JSON file that itemizes the specific build + and includes build summary information. + The following is sample output for a specific build: + <literallayout class='monospaced'> + {"build": + {"distro": "poky", + "errors": 0, + "machine": "beaglebone", + "project": "my_rocko", + "stop": "2017-09-22T09:26:36.017Z", + "target": "quilt-native", + "seconds": "78.193", + "outcome": "Succeeded", + "id": 1, + "start": "2017-09-22T09:25:17.824Z", + "warnings": 1, + "name": "20170922092618", + "cooker_log": "/opt/user/poky/build-toaster-2/tmp/log/cooker/beaglebone/build_20170922_022607.991.log" + } + } + </literallayout> + The JSON data for this query is returned in a single line. + In the previous example the line has been artificially split for readability. + </para> + </section> + </section> + <section id='toaster-useful-commands'> <title>Useful Commands</title> @@ -870,7 +677,7 @@ created that are specific to Toaster and are used to control configuration and back-end tasks. You can locate these commands in the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> (e.g. <filename>poky</filename>) at <filename>bitbake/lib/manage.py</filename>. This section documents those commands. @@ -879,7 +686,7 @@ When using <filename>manage.py</filename> commands given a default configuration, you must be sure that your working directory is set to the - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. Using <filename>manage.py</filename> commands from the Build Directory allows Toaster to find the <filename>toaster.sqlite</filename> file, which is located @@ -1005,30 +812,6 @@ </para> </section> - <section id='toaster-command-loadconf'> - <title><filename>loadconf</filename></title> - - <para> - The <filename>loadconf</filename> command loads an - existing Toaster configuration file (JSON file). - You must run this on a new database that does not have any - data. - Running this command on an existing database that has data - results in errors. - Access the command as follows: - <literallayout class='monospaced'> - $ bitbake/lib/toaster/manage.py loadconf <replaceable>filepath</replaceable> - </literallayout> - The <filename>loadconf</filename> command configures a database - based on the supplied existing - <filename>toasterconf.json</filename> file. - For information on the <filename>toasterconf.json</filename>, - see the - "<link linkend='toaster-json-files'>JSON Files</link>" - section. - </para> - </section> - <section id='toaster-command-runbuilds'> <title><filename>runbuilds</filename></title> diff --git a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml index 966c35d4d..c26a32a3d 100644 --- a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml +++ b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml @@ -18,7 +18,7 @@ <para> Navigate to the root of your - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> (e.g. <filename>poky</filename>): <literallayout class='monospaced'> $ cd poky @@ -61,19 +61,32 @@ </para> </section> - <section id='setting-a-different-address'> - <title>Setting a Different Address</title> + <section id='setting-up-external-access'> + <title>Setting up External Access</title> <para> By default, Toaster binds to the loop back address - (i.e. localhost). - You can use the <filename>WEBPORT</filename> parameter to - set a different host. - For example, the following command sets the host and port - to "0.0.0.0:8400": + (i.e. localhost), which does not allow access from + external hosts. To allow external access, use the + <filename>WEBPORT</filename> parameter to open an + address that connects to the network, specifically the + IP address that your NIC uses to connect to the network. + You can also bind to all IP addresses the computer + supports by using the shortcut + "0.0.0.0:<replaceable>port</replaceable>". + </para> + + <para> + The following example binds to all IP addresses on the + host: <literallayout class='monospaced'> $ source toaster start webport=0.0.0.0:8400 </literallayout> + This example binds to a specific IP address on the host's + NIC: + <literallayout class='monospaced'> + $ source toaster start webport=192.168.1.1:8400 + </literallayout> </para> </section> @@ -145,7 +158,7 @@ <listitem><para> From the directory containing the Toaster database, which by default is the - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>, invoke the <filename>createsuperuser</filename> command from <filename>manage.py</filename>: <literallayout class='monospaced'> @@ -369,16 +382,16 @@ <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> This line also runs the <filename>checksettings</filename> command, which configures the location of the Toaster - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build directory</ulink>. + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build directory</ulink>. The Toaster root directory <filename>TOASTER_DIR</filename> determines where the Toaster build directory is created on the file system. diff --git a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-start.xml b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-start.xml index c5c6795f6..65e057a83 100644 --- a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-start.xml +++ b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-start.xml @@ -41,7 +41,7 @@ The requirements file is located in the <filename>bitbake</filename> directory, which is located in the root directory of the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> (e.g. <filename>poky/bitbake/toaster-requirements.txt</filename>). The dependencies appear in a <filename>pip</filename>, install-compatible format. @@ -54,7 +54,7 @@ You need to install the packages that Toaster requires. Use this command: <literallayout class='monospaced'> - $ $ pip3 install --user -r bitbake/toaster-requirements.txt + $ pip3 install --user -r bitbake/toaster-requirements.txt </literallayout> The previous command installs the necessary Toaster modules into a local python 3 cache in your diff --git a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual.xml b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual.xml index c7a7fcd78..5a1b60e58 100644 --- a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual.xml +++ b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual.xml @@ -22,11 +22,11 @@ <authorgroup> <author> - <firstname>Scott</firstname> <surname>Rifenbark</surname> + <firstname>Kristi</firstname> <surname>Rifenbark</surname> <affiliation> - <orgname>Intel Corporation</orgname> + <orgname>Scotty's Documentation Services, INC</orgname> </affiliation> - <email>srifenbark@gmail.com</email> + <email>kristi@buzzcollectivemarketing.com</email> </author> </authorgroup> @@ -57,24 +57,19 @@ <revremark>Released with the Yocto Project 2.3 Release.</revremark> </revision> <revision> - <revnumber>2.3.1</revnumber> - <date>June 2017</date> - <revremark>Released with the Yocto Project 2.3.1 Release.</revremark> + <revnumber>2.4</revnumber> + <date>October 2017</date> + <revremark>Released with the Yocto Project 2.4 Release.</revremark> </revision> <revision> - <revnumber>2.3.2</revnumber> - <date>September 2017</date> - <revremark>Released with the Yocto Project 2.3.2 Release.</revremark> - </revision> - <revision> - <revnumber>2.3.3</revnumber> + <revnumber>2.4.1</revnumber> <date>January 2018</date> - <revremark>Released with the Yocto Project 2.3.3 Release.</revremark> + <revremark>Released with the Yocto Project 2.4.1 Release.</revremark> </revision> <revision> - <revnumber>2.3.4</revnumber> - <date>April 2018</date> - <revremark>Released with the Yocto Project 2.3.4 Release.</revremark> + <revnumber>2.4.2</revnumber> + <date>March 2018</date> + <revremark>Released with the Yocto Project 2.4.2 Release.</revremark> </revision> </revhistory> @@ -91,27 +86,29 @@ <note><title>Manual Notes</title> <itemizedlist> <listitem><para> - For the latest version of the Yocto Project Toaster - User Manual associated with this Yocto Project release - (version &YOCTO_DOC_VERSION;), - see the Yocto Project Toaster User Manual from the + This version of the + <emphasis>Toaster User Manual</emphasis> + is for the &YOCTO_DOC_VERSION; release of the + Yocto Project. + To be sure you have the latest version of the manual + for this release, use the manual from the <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>. </para></listitem> <listitem><para> - This version of the manual is version - &YOCTO_DOC_VERSION;. - For later releases of the Yocto Project (if they exist), - go to the + For manuals associated with other releases of the Yocto + Project, go to the <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink> and use the drop-down "Active Releases" button - and choose the Yocto Project version for which you want - the manual. + and choose the manual associated with the desired + Yocto Project. </para></listitem> <listitem><para> - For an in-development version of the Yocto Project - Toaster User Manual, see - <ulink url='&YOCTO_DOCS_URL;/latest/toaster-manual/toaster-manual.html'></ulink>. - </para></listitem> + To report any inaccuracies or problems with this + manual, send an email to the Yocto Project + discussion group at + <filename>yocto@yoctoproject.com</filename> or log into + the freenode <filename>#yocto</filename> channel. + </para></listitem> </itemizedlist> </note> |