diff options
Diffstat (limited to 'documentation/toaster-manual/toaster-manual-reference.xml')
| -rw-r--r-- | documentation/toaster-manual/toaster-manual-reference.xml | 1069 |
1 files changed, 1069 insertions, 0 deletions
diff --git a/documentation/toaster-manual/toaster-manual-reference.xml b/documentation/toaster-manual/toaster-manual-reference.xml new file mode 100644 index 0000000000..05184fa1eb --- /dev/null +++ b/documentation/toaster-manual/toaster-manual-reference.xml @@ -0,0 +1,1069 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<chapter id='toaster-manual-reference'> + +<title>Concepts and Reference</title> + + <para> + In order to configure and use Toaster, you should understand some + concepts and have some basic command reference material available. + This final chapter provides conceptual information on layer sources, + releases, and JSON configuration files. + Also provided is a quick look at some useful + <filename>manage.py</filename> commands. + Information on <filename>manage.py</filename> commands does exist + across the Web and the information in this manual by no means + attempts to provide a command reference. + However, having relevant command useful for the Toaster context + is helpful. + </para> + + <section id='layer-source'> + <title>Layer Source</title> + + <para> + In general, a layer source is some source of existing layers. + In particular, we are concerned with layers that you can use + with the Yocto Project and Toaster. + This chapter describes a particular type of layer source called + a "layer index." + </para> + + <para> + A layer index is a web application that contains information + about a set of custom layers. + A good example of an existing layer index is the + OpenEmbedded Metadata Index. + A public instance of this layer index exists at + <ulink url='http://layers.openembedded.org'></ulink>. + You can find the code for this layer index's web application at + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/layerindex-web/'></ulink>. + </para> + + <para> + When you tie a layer source into Toaster, it can query the layer + source through a + <ulink url='http://en.wikipedia.org/wiki/Representational_state_transfer'>REST</ulink> + API, store the information about the layers in the Toaster + database, and then show the information to users. + Users are then able to view that information and build layers + from Toaster itself without worrying about cloning or editing + the BitBake layers configuration file + <filename>bblayers.conf</filename>. + </para> + + <para> + Tying a layer source into Toaster is convenient when you have + many custom layers that need to be built on a regular basis by + a community of developers. + In fact, Toaster comes pre-configured with the OpenEmbedded + Metadata Index. + <note> + You do not have to use a layer source to use Toaster. + Tying into a layer source is optional. + </note> + </para> + + <section id='layer-source-using-with-toaster'> + <title>Setting Up and Using a Layer Source</title> + + <para> + To use your own layer source, you need to set up the layer + source and then tie it into Toaster. + This section describes how to tie into a layer index in a manner + similar to the way Toaster ties into the OpenEmbedded Metadata + Index. + </para> + + <section id='understanding-your-layers'> + <title>Understanding Your Layers</title> + + <para> + The obvious first step for using a layer index is to have + several custom layers that developers build and access using + the Yocto Project on a regular basis. + This set of layers needs to exist and you need to be + familiar with where they reside. + You will need that information when you set up the + code for the web application that "hooks" into your set of + layers. + </para> + + <para> + For general information on layers, see the + "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" + and + "<ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>Using the Yocto Project's BSP Tools</ulink>" + sections in the Yocto Project Board Support Package (BSP) + Developer's Guide. + </para> + </section> + + <section id='configuring-toaster-to-hook-into-your-layer-source'> + <title>Configuring Toaster to Hook Into Your Layer Index</title> + + <para> + If you want Toaster to use your layer index, you must host + the web application in a server to which Toaster can + connect. + You also need to give Toaster the information about your + layer index. + In other words, you have to configure Toaster to use your + layer index. + This section describes two methods by which you can + configure and use your layer index. + </para> + + <para> + In the previous section, the code for the OpenEmbedded + Metadata Index (i.e. + <ulink url='http://layers.openembedded.org'></ulink>) was + referenced. + You can use this code, which is at + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/layerindex-web/'></ulink>, + as a base to create your own layer index. + </para> + + <section id='use-the-administration-interface'> + <title>Use the Administration Interface</title> + + <para> + Access the administration interface through a + browser by entering the URL of your Toaster instance and + adding "<filename>/admin</filename>" to the end of the + URL. + </para> + + <para> + The administration interface has a "Layer sources" + section that includes an "Add layer source" button. + Click that button and provide the required information. + Make sure you select "layerindex" as the layer source type. + </para> + </section> + + <section id='select-the-toasterconf-json-file'> + <title>Select the <filename>toasterconf.json</filename> File</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> + When you set up Toaster in Build Mode, you are prompted to + select a Toaster configuration file. + This configuration file is used to set up the initial + configuration values within the Toaster database + including the layer sources. + Three 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-yocto</filename> layer + (i.e. + <filename>meta-yocto/conf/toasterconf.json</filename>). + 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 had cloned the + <filename>poky</filename> repository (i.e. + <filename>git://git.yoctoproject.org/poky</filename>). + </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. + 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> + <listitem><para> + The third version is a sample configuration + useful for when you want to set up a hosted + service in Build Mode. + You can find this version on the + <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>File:Toasterconf.json.txt.patch</ulink> + wiki page. + </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: + <literallayout class='monospaced'> + "layersources": [ + { + "name": "Local Yocto Project", + "sourcetype": "local", + "apiurl": "../../", + "branches": ["HEAD", "master", "fido", "dizzy"], + "layers": [ + { + "name": "openembedded-core", + "local_path": "meta", + "vcs_url": "remote:origin", + "dirpath": "meta" + }, + { + "name": "meta-yocto", + "local_path": "meta-yocto", + "vcs_url": "remote:origin", + "dirpath": "meta-yocto" + }, + { + "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", "fido", "dizzy"] + }, + { + "name": "Imported layers", + "sourcetype": "imported", + "apiurl": "", + "branches": ["master", "fido", "dizzy", "HEAD"] + + } + ], + </literallayout> + You should add your own layer source to this section by + following the same format used for the "OpenEmbedded" + layer source shown above. + </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 "dizzy" + 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. + </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-yocto/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-yocto/conf/toasterconf.json + </literallayout> + After entering this command, you need to update the + information from the layer index to populate the + Toaster database with the information from your layer + index. + To do that, you should run the + "<filename>lsupdates</filename>" command from the directory + that contains the Toaster database. + Here is an example: + <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 index should be listed there. + </para> + </section> + </section> + </section> + </section> + + <section id='toaster-releases'> + <title>Releases</title> + + <para> + In the context of Toaster, the term "Release" refers to a set of + layers and a BitBake version the OpenEmbedded build system uses + to build something. + As shipped, Toaster is pre-configured with releases that + correspond to Yocto Project release branches. + However, you can modify, delete, and create new releases + according to your needs. + When you create a Toaster project using the web interface, + you are asked to choose a "Release." + This section provides some background information on releases. + </para> + + <section id='toaster-releases-supported'> + <title>Pre-Configured Releases</title> + + <para> + As shipped, Toaster is configured to use a specific set of + releases. + Of course, you can always configure Toaster to use any + release. + For example, you might want your project to build against a + specific commit of any of the "out-of-the-box" releases. + Or, you might want your project to build against different + revisions of OpenEmbedded and BitBake. + </para> + + <para> + As shipped, Toaster is configured to work with the following + releases: + <itemizedlist> + <listitem><para><emphasis>Yocto Project 1.7 "Dizzy" or OpenEmbedded "Dizzy":</emphasis> + This release causes your Toaster projects to + build against the head of the dizzy branch at + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/?h=dizzy'></ulink> + or + <ulink url='http://git.openembedded.org/openembedded-core/commit/?h=dizzy'></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>. + </para></listitem> + <listitem><para><emphasis>Yocto Project "Master" or OpenEmbedded "Master":</emphasis> + This release causes your Toaster Projects to + build against the head of the master branch, which is + where active development takes place, at + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/'></ulink> + or + <ulink url='http://git.openembedded.org/openembedded-core/log/'></ulink>. + </para></listitem> + <listitem><para><emphasis>Local Yocto Project or Local OpenEmbedded:</emphasis> + This release causes your Toaster Projects to + build against the head of the <filename>poky</filename> + or <filename>openembedded-core</filename> clone you + have local to the machine running Toaster. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='toaster-releases-comprised-of'> + <title>What Makes Up a Release?</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 "dizzy" branches are available. + </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. + You can download the recommended configuration + for this case from + <ulink url='&YOCTO_WIKI_URL;/wiki/File:Toasterconf.json.txt.patch'></ulink>. + </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. + </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. + </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 sets it to + use the master branch of the + <filename>openembedded-core</filename> layer. + 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 OpenEmbedded master branch, where active development takes place. This is not a stable branch, so your builds might not work as expected." + } + ] + </literallayout> + </para> + </section> + </section> + + <section id='toaster-json-files'> + <title>JSON Files</title> + + <para> + If you are going to be using the Toaster in Build Mode, it must + be initially configured before use. + 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 + admin web interface. + </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. + In the Local Toaster Build Mode, the system startup script + actively looks for compatible configuration files and prompts + you to select a file to load if it detects that the database has + not been configured. + </para> + + <section id='json-file-choices'> + <title>Configuration File Choices</title> + + <para> + Three versions of the configuration file exist: + <itemizedlist> + <listitem><para> + The + <filename>meta-yocto/conf/toasterconf.json</filename> + in the <filename>conf</filename> directory of the + Yocto Project's <filename>meta-yocto</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> + <listitem><para> + The <filename>Toasterconf.json.txt.patch</filename> + located on the + <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>File:Toasterconf.json.txt.patch</ulink> + wiki page. + This version of the file is useful as a sample + configuration for when you want to set up Toaster as a + hosted service in Build Mode. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='json-structure'> + <title>File Structure</title> + + <para> + The <filename>toasterconf.json</filename> file consists of + easily readable areas: configuration, layer sources, BitBake, + default, and releases. + </para> + + <section id='json-config-area'> + <title>Configuration Area</title> + + <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 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: + <literallayout class='monospaced'> + "config": { + "MACHINE" : "qemux86", + "DISTRO" : "poky", + "IMAGE_FSTYPES": "ext3 jffs2 tar.bz2", + "IMAGE_INSTALL_append": "", + "PACKAGE_CLASSES": "package_rpm", + "SDKMACHINE" : "x86_64" + }, + </literallayout> + </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> + + <para> + Here is the default <filename>layersources</filename> area: + <literallayout class='monospaced'> + "layersources": [ + { + "name": "Local Yocto Project", + "sourcetype": "local", + "apiurl": "../../", + "branches": ["HEAD", "master", "fido", "dizzy"], + "layers": [ + { + "name": "openembedded-core", + "local_path": "meta", + "vcs_url": "remote:origin", + "dirpath": "meta" + }, + { + "name": "meta-yocto", + "local_path": "meta-yocto", + "vcs_url": "remote:origin", + "dirpath": "meta-yocto" + }, + { + "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", "fido", "dizzy"] + }, + { + "name": "Imported layers", + "sourcetype": "imported", + "apiurl": "", + "branches": ["master", "fido", "dizzy", "HEAD"] + + } + ], + </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 three + versions of BitBake: master, dizzy, and HEAD. + </para> + + <para> + Here is the default <filename>bitbake</filename> area: + <literallayout class='monospaced'> + "bitbake" : [ + { + "name": "master", + "giturl": "remote:origin", + "branch": "master", + "dirpath": "bitbake" + }, + { + "name": "fido", + "giturl": "remote:origin", + "branch": "fido", + "dirpath": "bitbake" + }, + { + "name": "dizzy", + "giturl": "remote:origin", + "branch": "dizzy", + "dirpath": "bitbake" + }, + { + "name": "HEAD", + "giturl": "remote:origin", + "branch": "HEAD", + "dirpath": "bitbake" + } + ], + </literallayout> + </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> + + <para> + Here is the statement in the JSON file that establishes + the default release: + <literallayout class='monospaced'> + "defaultrelease": "master", + </literallayout> + </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> + + <para> + Here is the default <filename>releases</filename> area: + <literallayout class='monospaced'> + "releases": [ + { + "name": "master", + "description": "Yocto Project master", + "bitbake": "master", + "branch": "master", + "defaultlayers": [ "openembedded-core", "meta-yocto", "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": "fido", + "description": "Yocto Project 1.8 Fido", + "bitbake": "fido", + "branch": "fido", + "defaultlayers": [ "openembedded-core", "meta-yocto", "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": "dizzy", + "description": "Yocto Project 1.7 Dizzy", + "bitbake": "dizzy", + "branch": "dizzy", + "defaultlayers": [ "openembedded-core", "meta-yocto", "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=dizzy\">Yocto Project 1.7 \"Dizzy\"</a> branch." + }, + { + "name": "local", + "description": "Local Yocto Project", + "bitbake": "HEAD", + "branch": "HEAD", + "defaultlayers": [ "openembedded-core", "meta-yocto", "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." + } + ] + </literallayout> + </para> + </section> + </section> + </section> + + <section id='toaster-useful-commands'> + <title>Useful Commands</title> + + <para> + In addition to the web user interface and the scripts that start + and stop Toaster, command-line commands exist through the + <filename>manage.py</filename> management script. + You can find general documentation on + <filename>manage.py</filename> at the + <ulink url='https://docs.djangoproject.com/en/1.7/topics/settings/'>Django</ulink> + site. + However, several <filename>manage.py</filename> commands have been + 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> + (e.g. <filename>poky</filename>) at + <filename>bitbake/lib/manage.py</filename>. + This section documents those commands. + <note> + <para> + 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>. + Using <filename>manage.py</filename> commands from the + Build Directory allows Toaster to find the + <filename>toaster.sqlite</filename> file, which is located + in the Build Directory. + </para> + + <para> + For non-default database configurations, it is possible + that you can use <filename>manage.py</filename> commands + from a directory other than the Build directory. + To do so, the + <filename>toastermain/settings.py</filename> file must be + configured to point to the correct database backend. + </para> + </note> + </para> + + <section id='toaster-command-buildslist'> + <title><filename>buildslist</filename></title> + + <para> + The <filename>buildslist</filename> command lists all builds + that Toaster has recorded. + Access the command as follows: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py buildslist + </literallayout> + The command returns a list, which includes numeric + identifications, of the builds that Toaster has recorded in the + current database. + </para> + + <para> + You need to run the <filename>buildslist</filename> command + first to identify existing builds in the database before + using the + <link linkend='toaster-command-builddelete'><filename>builddelete</filename></link> + command. + For example, assuming default repository and build directory + names, the following two commands put you in the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + and then return a list of the current builds, which would + be one in this case: + <literallayout class='monospaced'> + $ cd $HOME/poky/build + $ python ../bitbake/lib/toaster/manage.py buildslist + 1: qemux86 poky core-image-minimal + </literallayout> + </para> + </section> + + <section id='toaster-command-builddelete'> + <title><filename>builddelete</filename></title> + + <para> + The <filename>builddelete</filename> command deletes data + associated with a build. + Access the command as follows: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py builddelete <replaceable>build_id</replaceable> + </literallayout> + The command deletes all the build data for the specified + <replaceable>build_id</replaceable>. + This command is useful for removing old and unused data from + the database. + </para> + + <para> + Prior to running the <filename>builddelete</filename> + command, you need to get the ID associated with builds + by using the + <link linkend='toaster-command-buildslist'><filename>buildslist</filename></link> + command. + </para> + </section> + + <section id='toaster-command-perf'> + <title><filename>perf</filename></title> + + <para> + The <filename>perf</filename> command measures Toaster + performance. + Access the command as follows: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py perf + </literallayout> + The command is a sanity check that returns page loading + times in order to identify performance problems. + </para> + </section> + + <section id='toaster-command-checksettings'> + <title><filename>checksettings</filename></title> + + <para> + The <filename>checksettings</filename> command verifies + existing Toaster settings. + Access the command as follows: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py checksettings + </literallayout> + In Managed Mode, Toaster uses settings that are based on the + database to configure the building tasks. + The <filename>checksettings</filename> command verifies that + the database settings are valid in the sense that they have + the minimal information needed to start a build. + </para> + + <para> + In order for the <filename>checksettings</filename> command + to work, the database must be correctly set up and not have + existing data. + To be sure the database is ready, you can run the following: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py syncdb + $ bitbake/lib/toaster/manage.py migrate orm + $ bitbake/lib/toaster/manage.py migrate bldcontrol + </literallayout> + After running these commands, you can run the + <filename>checksettings</filename> command. + </para> + </section> + + <section id='toaster-command-loadconf'> + <title><filename>loadconf</filename></title> + + <para> + The <filename>loadconf</filename> command loads a 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 <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> + + <para> + The <filename>runbuilds</filename> command launched + scheduled builds. + Access the command as follows: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py runbuilds + </literallayout> + The <filename>runbuilds</filename> command checks if + scheduled builds exist in the database and then launches them + per schedule. + The command returns after the builds start but before they + complete. + The "toasterui" build recorded updates the database when the + builds complete. + </para> + </section> + </section> +</chapter> |