diff options
Diffstat (limited to 'poky/documentation/toaster-manual')
17 files changed, 3107 insertions, 0 deletions
diff --git a/poky/documentation/toaster-manual/figures/add-variable.png b/poky/documentation/toaster-manual/figures/add-variable.png Binary files differnew file mode 100644 index 000000000..6bdcca705 --- /dev/null +++ b/poky/documentation/toaster-manual/figures/add-variable.png diff --git a/poky/documentation/toaster-manual/figures/bash-oecore.png b/poky/documentation/toaster-manual/figures/bash-oecore.png Binary files differnew file mode 100644 index 000000000..801a5d911 --- /dev/null +++ b/poky/documentation/toaster-manual/figures/bash-oecore.png diff --git a/poky/documentation/toaster-manual/figures/compatible-layers.png b/poky/documentation/toaster-manual/figures/compatible-layers.png Binary files differnew file mode 100644 index 000000000..38436b075 --- /dev/null +++ b/poky/documentation/toaster-manual/figures/compatible-layers.png diff --git a/poky/documentation/toaster-manual/figures/hosted-service.png b/poky/documentation/toaster-manual/figures/hosted-service.png Binary files differnew file mode 100644 index 000000000..01fea7b24 --- /dev/null +++ b/poky/documentation/toaster-manual/figures/hosted-service.png diff --git a/poky/documentation/toaster-manual/figures/import-layer.png b/poky/documentation/toaster-manual/figures/import-layer.png Binary files differnew file mode 100644 index 000000000..436ec7af4 --- /dev/null +++ b/poky/documentation/toaster-manual/figures/import-layer.png diff --git a/poky/documentation/toaster-manual/figures/new-project.png b/poky/documentation/toaster-manual/figures/new-project.png Binary files differnew file mode 100644 index 000000000..dbc50b991 --- /dev/null +++ b/poky/documentation/toaster-manual/figures/new-project.png diff --git a/poky/documentation/toaster-manual/figures/set-variable.png b/poky/documentation/toaster-manual/figures/set-variable.png Binary files differnew file mode 100644 index 000000000..d36b52754 --- /dev/null +++ b/poky/documentation/toaster-manual/figures/set-variable.png diff --git a/poky/documentation/toaster-manual/figures/simple-configuration.png b/poky/documentation/toaster-manual/figures/simple-configuration.png Binary files differnew file mode 100644 index 000000000..e8fce2bf1 --- /dev/null +++ b/poky/documentation/toaster-manual/figures/simple-configuration.png diff --git a/poky/documentation/toaster-manual/figures/toaster-title.png b/poky/documentation/toaster-manual/figures/toaster-title.png Binary files differnew file mode 100644 index 000000000..b7ea39cd8 --- /dev/null +++ b/poky/documentation/toaster-manual/figures/toaster-title.png diff --git a/poky/documentation/toaster-manual/figures/variable-added.png b/poky/documentation/toaster-manual/figures/variable-added.png Binary files differnew file mode 100644 index 000000000..518f25fa1 --- /dev/null +++ b/poky/documentation/toaster-manual/figures/variable-added.png diff --git a/poky/documentation/toaster-manual/toaster-manual-customization.xsl b/poky/documentation/toaster-manual/toaster-manual-customization.xsl new file mode 100644 index 000000000..d78694ac1 --- /dev/null +++ b/poky/documentation/toaster-manual/toaster-manual-customization.xsl @@ -0,0 +1,28 @@ +<?xml version='1.0'?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> + + <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> + +<!-- + + <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> + + <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" /> + +--> + + <xsl:include href="../template/permalinks.xsl"/> + <xsl:include href="../template/section.title.xsl"/> + <xsl:include href="../template/component.title.xsl"/> + <xsl:include href="../template/division.title.xsl"/> + <xsl:include href="../template/formal.object.heading.xsl"/> + <xsl:include href="../template/embedded_video.xsl"/> + + <xsl:param name="html.stylesheet" select="'toaster-manual-style.css'" /> + <xsl:param name="chapter.autolabel" select="1" /> + <xsl:param name="appendix.autolabel" select="A" /> + <xsl:param name="section.autolabel" select="1" /> + <xsl:param name="section.label.includes.component.label" select="1" /> + <xsl:param name="generate.id.attributes" select="1" /> + +</xsl:stylesheet> diff --git a/poky/documentation/toaster-manual/toaster-manual-intro.xml b/poky/documentation/toaster-manual/toaster-manual-intro.xml new file mode 100644 index 000000000..e84964c4e --- /dev/null +++ b/poky/documentation/toaster-manual/toaster-manual-intro.xml @@ -0,0 +1,164 @@ +<!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-intro'> +<title>Introduction</title> + + <para> + Toaster is a web interface to the Yocto Project's + <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 + remote build servers. + </para> + + <section id='intro-features'> + <title>Toaster Features</title> + + <para> + Toaster allows you to configure and run builds, and it + provides extensive information about the build process. + <itemizedlist> + <listitem><para id='toaster-build-features'> + <emphasis>Configure and Run Builds:</emphasis> + You can use the Toaster web interface to configure and + start your builds. + Builds started using the Toaster web interface are + organized into projects. + When you create a project, you are asked to select a + release, or version of the build system you want to + use for the project builds. + As shipped, Toaster supports Yocto Project releases 1.8 + and beyond. + With the Toaster web interface, you can: + <itemizedlist> + <listitem><para> + Browse layers listed in the various + <link linkend='layer-source'>layer sources</link> + that are available in your project (e.g. the + OpenEmbedded Layer Index at + <ulink url='http://layers.openembedded.org/layerindex/'></ulink>). + </para></listitem> + <listitem><para> + Browse images, recipes, and machines provided by + those layers. + </para></listitem> + <listitem><para> + Import your own layers for building. + </para></listitem> + <listitem><para> + Add and remove layers from your configuration. + </para></listitem> + <listitem><para> + Set configuration variables. + </para></listitem> + <listitem><para> + Select a target or multiple targets to build. + </para></listitem> + <listitem><para> + Start your builds. + </para></listitem> + </itemizedlist> + Toaster also allows you to configure and run your builds + from the command line, and switch between the command line and + the web interface at any time. + Builds started from the command line appear within a special + Toaster project called "Command line builds". + </para></listitem> + <listitem><para id='toaster-analysis-features'> + <emphasis>Information About the Build Process:</emphasis> + Toaster also records extensive information about your builds. + Toaster collects data for builds you start from the web + interface and from the command line as long as Toaster + is running. + <note> + You must start Toaster before the build or it will not + collect build data. + </note></para> + <para>With Toaster you can: + <itemizedlist> + <listitem><para> + See what was built (recipes and packages) and what + packages were installed into your final image. + </para></listitem> + <listitem><para> + Browse the directory structure of your image. + </para></listitem> + <listitem><para> + See the value of all variables in your build + configuration, and which files set each value. + </para></listitem> + <listitem><para> + Examine error, warning, and trace messages to aid + in debugging. + </para></listitem> + <listitem><para> + See information about the BitBake tasks executed + and reused during your build, including those that + used shared state. + </para></listitem> + <listitem><para> + See dependency relationships between recipes, + packages, and tasks. + </para></listitem> + <listitem><para> + See performance information such as build time, + task time, CPU usage, and disk I/O. + </para></listitem> + </itemizedlist> + </para></listitem> + </itemizedlist> + </para> + + <para> + For an overview of Toaster shipped with the Yocto Project &DISTRO; + Release, see the + "<ulink url='https://youtu.be/BlXdOYLgPxA'>Toaster - Yocto Project 2.2</ulink>" + video. + </para> + </section> + + <section id='toaster-installation-options'> + <title>Installation Options</title> + + <para> + You can set Toaster up to run as a local instance or as a shared + hosted service. + </para> + + <para> + When Toaster is set up as a local instance, all the components + reside on a single build host. + Fundamentally, a local instance of Toaster is suited for a single + user developing on a single build host. + </para> + + <para> + <imagedata fileref="figures/simple-configuration.png" align="center" width="6in" depth="1.5in" /> + </para> + + <para> + Toaster as a hosted service is suited for multiple users + developing across several build hosts. + When Toaster is set up as a hosted service, its components can + be spread across several machines: + </para> + + <para> + <imagedata fileref="figures/hosted-service.png" align="center" width="6in" depth="3.5in" /> + </para> + </section> + +<!--THIS EXTRA INFORMATION PROBABLY WILL GO AWAY + For additional information on installing and running Toaster, see the + "<ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Installation_and_Running'>Installation and Running</ulink>" + section of the "Toaster" wiki page. + For complete information on the API and its search operation + URI, parameters, and responses, see the + <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink> + Wiki page. + </para> +--> +</chapter> diff --git a/poky/documentation/toaster-manual/toaster-manual-reference.xml b/poky/documentation/toaster-manual/toaster-manual-reference.xml new file mode 100644 index 000000000..7440580e7 --- /dev/null +++ b/poky/documentation/toaster-manual/toaster-manual-reference.xml @@ -0,0 +1,836 @@ +<!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 that are Toaster-specific. + 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 comprehensive reference. + </para> + + <section id='layer-source'> + <title>Layer Source</title> + + <para> + In general, a "layer source" is a source of information about + 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 Layer 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_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>" + section in the Yocto Project Overview and Concepts Manual. + For information on how to create layers, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" + section in the Yocto Project Development Tasks Manual. + </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. + As an example, if you are running Toaster locally, use + the following URL: + <literallayout class='monospaced'> + http://127.0.0.1:8000/admin + </literallayout> + </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='use-the-fixture-feature'> + <title>Use the Fixture Feature</title> + + <para> + 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'> + <?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> + 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> + 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> + 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> + </section> + </section> + </section> + </section> + + <section id='toaster-releases'> + <title>Releases</title> + + <para> + When you create a Toaster project using the web interface, + you are asked to choose a "Release." + 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. + 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 &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 + 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> + + <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='configuring-the-workflow'> + <title>Configuring the Workflow</title> + + <para> + 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> + 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> + 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='customizing-pre-set-data'> + <title>Customizing Pre-Set Data</title> + + <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> + 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> + + <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> + 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='understanding-fixture-file-format'> + <title>Understanding Fixture File Format</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> + 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-and-other-values'> + <title>Defining the Default Distro and Other Values</title> + + <para> + 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> + 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='defining-bitbake-version'> + <title>Defining BitBake Version</title> + + <para> + The following defines which version of BitBake is used + for the following release selection: + <literallayout class='monospaced'> + <!-- 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='defining-releases'> + <title>Defining Release</title> + + <para> + The following defines the releases when you create a new + project. + <literallayout class='monospaced'> + <!-- 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='defining-the-release-default-layer-names'> + <title>Defining the Release Default Layer Names</title> + + <para> + The following defines the default layers for each release: + <literallayout class='monospaced'> + <!-- 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='defining-layer-definitions'> + <title>Defining Layer Definitions</title> + + <para> + 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'> + <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> + + <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_REF_URL;#source-directory'>Source Directory</ulink> + (e.g. <filename>poky</filename>) at + <filename>bitbake/lib/manage.py</filename>. + This section documents those commands. + <note><title>Notes</title> + <itemizedlist> + <listitem><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_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 + in the Build Directory. + </para></listitem> + <listitem><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></listitem> + </itemizedlist> + </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. + Here is an example that assumes default repository and build + directory names: + <literallayout class='monospaced'> + $ cd ~/poky/build + $ python ../bitbake/lib/toaster/manage.py buildslist + </literallayout> + If your Toaster database had only one build, the above + <filename>buildslist</filename> command would return something + like the following: + <literallayout class='monospaced'> + 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> + 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-runbuilds'> + <title><filename>runbuilds</filename></title> + + <para> + The <filename>runbuilds</filename> command launches + 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 Toaster Logging Interface records and updates the database + when the builds complete. + </para> + </section> + </section> +</chapter> diff --git a/poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml new file mode 100644 index 000000000..b4caebbe0 --- /dev/null +++ b/poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml @@ -0,0 +1,843 @@ +<!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-setup-and-use'> + +<title>Setting Up and Using Toaster</title> + + <section id='starting-toaster-for-local-development'> + <title>Starting Toaster for Local Development</title> + + <para> + Once you have set up the Yocto Project and installed the + Toaster system dependencies as described in the + "<link linkend='toaster-manual-start'>Preparing to Use Toaster</link>" + chapter, you are ready to start Toaster. + </para> + + <para> + Navigate to the root of your + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> + (e.g. <filename>poky</filename>): + <literallayout class='monospaced'> + $ cd poky + </literallayout> + Once in that directory, source the build environment script: + <literallayout class='monospaced'> + $ source oe-init-build-env + </literallayout> + Next, from the build directory (e.g. + <filename>poky/build</filename>), start Toaster using this + command: + <literallayout class='monospaced'> + $ source toaster start + </literallayout> + You can now run your builds from the command line, or with + Toaster as explained in section + "<link linkend='using-the-toaster-web-interface'>Using the Toaster Web Interface</link>". + </para> + + <para> + To access the Toaster web interface, open your favorite + browser and enter the following: + <literallayout class='monospaced'> + http://127.0.0.1:8000 + </literallayout> + </para> + </section> + + <section id='setting-a-different-port'> + <title>Setting a Different Port</title> + + <para> + By default, Toaster starts on port 8000. + You can use the <filename>WEBPORT</filename> parameter to + set a different port. + For example, the following command sets the port to "8400": + <literallayout class='monospaced'> + $ source toaster start webport=8400 + </literallayout> + </para> + </section> + + <section id='setting-up-toaster-without-a-web-server'> + <title>Setting Up Toaster Without a Web Server</title> + + <para> + You can start a Toaster environment without starting its + web server. This is useful for the following: + <itemizedlist> + <listitem><para> + Capturing a command-line build’s statistics into + the Toaster database for examination later. + </para></listitem> + <listitem><para> + Capturing a command-line build’s statistics when + the Toaster server is already running. + </para></listitem> + <listitem><para> + Having one instance of the Toaster web server + track and capture multiple command-line builds, + where each build is started in its own “noweb” + Toaster environment. + </para></listitem> + </itemizedlist> + The following commands show how to start a Toaster environment + without starting its web server, perform BitBake operations, + and then shut down the Toaster environment. + Once the build is complete, you can close the Toaster environment. + Before closing the environment, however, you should allow a few + minutes to ensure the complete transfer of its BitBake build + statistics to the Toaster database. + If you have a separate Toaster web server instance running, you + can watch this command-line build’s progress and examine the + results as soon as they are posted: + <literallayout class='monospaced'> + $ source toaster start noweb + $ bitbake <replaceable>target</replaceable> + $ source toaster stop + </literallayout> + </para> + </section> + + <section id='setting-up-toaster-without-a-build-server'> + <title>Setting Up Toaster Without a Build Server</title> + + <para> + You can start a Toaster environment with the + “New Projects” feature disabled. + Doing so is useful for the following: + <itemizedlist> + <listitem><para> + Sharing your build results over the web server while + blocking others from starting builds on your host. + </para></listitem> + <listitem><para> + Allowing only local command-line builds to be captured + into the Toaster database. + </para></listitem> + </itemizedlist> + Use the following command to set up Toaster without a + build server: + <literallayout class='monospaced'> + $ source toaster start nobuild webport=<replaceable>port</replaceable> + </literallayout> + </para> + </section> + + <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), 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> + + <section id='the-directory-for-cloning-layers'> + <title>The Directory for Cloning Layers</title> + + <para> + Toaster creates a <filename>_toaster_clones</filename> + directory inside your Source Directory + (i.e. <filename>poky</filename>) to clone any layers + needed for your builds. + </para> + + <para> + Alternatively, if you would like all of your Toaster related + files and directories to be in a particular location other than + the default, you can set the <filename>TOASTER_DIR</filename> + environment variable, which takes precedence over your current + working directory. + Setting this environment variable causes Toaster to create and use + <filename>$TOASTER_DIR./_toaster_clones</filename>. + </para> + </section> + + <section id='toaster-the-build-directory'> + <title>The Build Directory</title> + + <para> + Toaster creates a build directory within your Source + Directory (e.g. <filename>poky</filename>) to execute + the builds. + </para> + + <para> + Alternatively, if you would like all of your Toaster related files + and directories to be in a particular location, you can set + the <filename>TOASTER_DIR</filename> environment variable, + which takes precedence over your current working directory. + Setting this environment variable causes Toaster to use + <filename>$TOASTER_DIR/build</filename> as the build directory. + </para> + </section> + + <section id='toaster-creating-a-django-super-user'> + <title>Creating a Django Superuser</title> + + <para> + Toaster is built on the + <ulink url='https://www.djangoproject.com/'>Django framework</ulink>. + Django provides an administration interface you can use + to edit Toaster configuration parameters. + </para> + + <para> + To access the Django administration interface, you must + create a superuser by following these steps: + <orderedlist> + <listitem><para> + If you used <filename>pip3</filename>, which is + recommended, to set up the Toaster system dependencies, + you need be sure the local user path is in your + <filename>PATH</filename> list. + To append the pip3 local user path, use the following + command: + <literallayout class='monospaced'> + $ export PATH=$PATH:$HOME/.local/bin + </literallayout> + </para></listitem> + <listitem><para> + From the directory containing the Toaster database, + which by default is the + <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'> + $ cd ~/poky/build + $ ../bitbake/lib/toaster/manage.py createsuperuser + </literallayout> + </para></listitem> + <listitem><para> + Django prompts you for the username, which you need to + provide. + </para></listitem> + <listitem><para> + Django prompts you for an email address, which is + optional. + </para></listitem> + <listitem><para> + Django prompts you for a password, which you must provide. + </para></listitem> + <listitem><para> + Django prompts you to re-enter your password for verification. + </para></listitem> + </orderedlist> + After completing these steps, the following confirmation message + appears: + <literallayout class='monospaced'> + Superuser created successfully. + </literallayout> + </para> + + <para> + Creating a superuser allows you to access the Django administration + interface through a browser. + The URL for this interface is the same as the URL used for the + Toaster instance with "/admin" on the end. + For example, if you are running Toaster locally, use the + following URL: + <literallayout class='monospaced'> + http://127.0.0.1:8000/admin + </literallayout> + You can use the Django administration interface to set Toaster + configuration parameters such as the build directory, layer sources, + default variable values, and BitBake versions. + </para> + </section> + + <section id='toaster-setting-up-a-production-instance-of-toaster'> + <title>Setting Up a Production Instance of Toaster</title> + + <para> + You can use a production instance of Toaster to share the + Toaster instance with remote users, multiple users, or both. + The production instance is also the setup that can handle + heavier loads on the web service. + Use the instructions in the following sections to set up + Toaster to run builds through the Toaster web interface. + </para> + + <section id='toaster-production-instance-requirements'> + <title>Requirements</title> + + <para> + Be sure you meet the following requirements: + <note> + You must comply with all Apache, + <filename>mod-wsgi</filename>, and Mysql requirements. + </note> + <itemizedlist> + <listitem><para> + Have all the build requirements as described in the + "<link linkend='toaster-manual-start'>Preparing to Use Toaster</link>" + chapter. + </para></listitem> + <listitem><para> + Have an Apache webserver. + </para></listitem> + <listitem><para> + Have <filename>mod-wsgi</filename> for the Apache + webserver. + </para></listitem> + <listitem><para> + Use the Mysql database server. + </para></listitem> + <listitem><para> + If you are using Ubuntu 16.04, run the following: + <literallayout class='monospaced'> + $ sudo apt-get install apache2 libapache2-mod-wsgi-py3 mysql-server python3-pip libmysqlclient-dev + </literallayout> + </para></listitem> + <listitem><para> + If you are using Fedora 24 or a RedHat distribution, run + the following: + <literallayout class='monospaced'> + $ sudo dnf install httpd python3-mod_wsgi python3-pip mariadb-server mariadb-devel python3-devel + </literallayout> + </para></listitem> + <listitem><para> + If you are using openSUSE Leap 42.1, run + the following: + <literallayout class='monospaced'> + $ sudo zypper install apache2 apache2-mod_wsgi-python3 python3-pip mariadb mariadb-client python3-devel + </literallayout> + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='toaster-installation-steps'> + <title>Installation</title> + + <para> + Perform the following steps to install Toaster: + <orderedlist> + <listitem><para> + Create toaster user and set its home directory to + <filename>/var/www/toaster</filename>: + <literallayout class='monospaced'> + $ sudo /usr/sbin/useradd toaster -md /var/www/toaster -s /bin/false + $ sudo su - toaster -s /bin/bash + </literallayout> + </para></listitem> + <listitem><para> + Checkout a copy of <filename>poky</filename> + into the web server directory. + You will be using <filename>/var/www/toaster</filename>: + <literallayout class='monospaced'> + $ git clone git://git.yoctoproject.org/poky + $ git checkout &DISTRO_NAME_NO_CAP; + </literallayout> + </para></listitem> + <listitem><para> + Install Toaster + dependencies using the --user flag which + keeps the Python packages + isolated from your system-provided packages: + <literallayout class='monospaced'> + $ cd /var/www/toaster/ + $ pip3 install --user -r ./poky/bitbake/toaster-requirements.txt + $ pip3 install --user mysqlclient + </literallayout> + <note> + Isolating these packages is not required but is + recommended. + Alternatively, you can use your operating system's + package manager to install the packages. + </note> + </para></listitem> + <listitem><para> + Configure Toaster by editing + <filename>/var/www/toaster/poky/bitbake/lib/toaster/toastermain/settings.py</filename> + as follows: + <itemizedlist> + <listitem><para> + Edit the + <ulink url='https://docs.djangoproject.com/en/1.11/ref/settings/#databases'>DATABASES</ulink> + settings: + <literallayout class='monospaced'> + DATABASES = { + 'default': { + 'ENGINE': 'django.db.backends.mysql', + 'NAME': 'toaster_data', + 'USER': 'toaster', + 'PASSWORD': 'yourpasswordhere', + 'HOST': 'localhost', + 'PORT': '3306', + } + } + </literallayout> + </para></listitem> + <listitem><para> + Edit the + <ulink url='https://docs.djangoproject.com/en/1.11/ref/settings/#std:setting-SECRET_KEY'>SECRET_KEY</ulink>: + <literallayout class='monospaced'> + SECRET_KEY = '<replaceable>your_secret_key</replaceable>' + </literallayout> + </para></listitem> + <listitem><para> + Edit the + <ulink url='https://docs.djangoproject.com/en/1.11/ref/settings/#std:setting-STATIC_ROOT'>STATIC_ROOT</ulink>: + <literallayout class='monospaced'> + STATIC_ROOT = '/var/www/toaster/static_files/' + </literallayout> + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + Add the database and user to the <filename>mysql</filename> + server defined earlier: + <literallayout class='monospaced'> + $ mysql -u root -p + mysql> CREATE DATABASE toaster_data; + mysql> CREATE USER 'toaster'@'localhost' identified by 'yourpasswordhere'; + mysql> GRANT all on toaster_data.* to 'toaster'@'localhost'; + mysql> quit + </literallayout> + </para></listitem> + <listitem><para> + Get Toaster to create the database schema, + default data, and gather the statically-served files: + <literallayout class='monospaced'> + $ cd /var/www/toaster/poky/ + $ ./bitbake/lib/toaster/manage.py migrate + $ TOASTER_DIR=`pwd` TEMPLATECONF='poky' \ + ./bitbake/lib/toaster/manage.py checksettings + $ ./bitbake/lib/toaster/manage.py collectstatic + </literallayout> + In the previous example, from the <filename>poky</filename> + directory, the <filename>migrate</filename> command + ensures the database schema changes have propagated + correctly (i.e. migrations). + The next line sets the Toaster root directory + <filename>TOASTER_DIR</filename> and the location + of the Toaster configuration file + <filename>TOASTER_CONF</filename>, which is relative to + <filename>TOASTER_DIR</filename>. + The <filename>TEMPLATECONF</filename> value reflects the + contents of <filename>poky/.templateconf</filename>, and + by default, should include the string "poky". + For more information on the Toaster configuration + file, see the + "<link linkend='configuring-toaster'>Configuring Toaster</link>" + section.</para> + + <para>This line also runs the <filename>checksettings</filename> + command, which configures the location of the Toaster + <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. + In the example above, + <filename>TOASTER_DIR</filename> is set as follows: + <literallayout class="monospaced"> + /var/www/toaster/poky + </literallayout> + This setting causes the Toaster build directory to be: + <literallayout class="monospaced"> + /var/www/toaster/poky/build + </literallayout></para> + + <para>Finally, the <filename>collectstatic</filename> command + is a Django framework command that collects all the + statically served files into a designated directory to + be served up by the Apache web server as defined by + <filename>STATIC_ROOT</filename>. + </para></listitem> + <listitem><para> + Test and/or use the Mysql integration with Toaster’s + Django web server. + At this point, you can start up the normal Toaster + Django web server with the Toaster database in Mysql. + You can use this web server to confirm that the database + migration and data population from the Layer Index is + complete.</para> + + <para>To start the default Toaster Django web server with + the Toaster database now in Mysql, use the standard + start commands: + <literallayout class='monospaced'> + $ source oe-init-build-env + $ source toaster start + </literallayout> + Additionally, if Django is sufficient for your requirements, + you can use it for your release system and migrate later + to Apache as your requirements change. + </para></listitem> + <listitem><para> + Add an Apache configuration file for Toaster to your Apache web + server's configuration directory. + If you are using Ubuntu or Debian, put the file here: + <literallayout class='monospaced'> + /etc/apache2/conf-available/toaster.conf + </literallayout> + If you are using Fedora or RedHat, put it here: + <literallayout class='monospaced'> + /etc/httpd/conf.d/toaster.conf + </literallayout> + If you are using OpenSUSE, put it here: + <literallayout class='monospaced'> + /etc/apache2/conf.d/toaster.conf + </literallayout> + Following is a sample Apache configuration for Toaster + you can follow: + <literallayout class='monospaced'> + Alias /static /var/www/toaster/static_files + <Directory /var/www/toaster/static_files> + <IfModule mod_access_compat.c> + Order allow,deny + Allow from all + </IfModule> + <IfModule !mod_access_compat.c> + Require all granted + </IfModule> + </Directory> + + <Directory /var/www/toaster/poky/bitbake/lib/toaster/toastermain> + <Files "wsgi.py"> + Require all granted + </Files> + </Directory> + + WSGIDaemonProcess toaster_wsgi python-path=/var/www/toaster/poky/bitbake/lib/toaster:/var/www/toaster/.local/lib/python3.4/site-packages + + WSGIScriptAlias / "/var/www/toaster/poky/bitbake/lib/toaster/toastermain/wsgi.py" + <Location /> + WSGIProcessGroup toaster_wsgi + </Location> + </literallayout> + If you are using Ubuntu or Debian, + you will need to enable the config and module for Apache: + <literallayout class='monospaced'> + $ sudo a2enmod wsgi + $ sudo a2enconf toaster + $ chmod +x bitbake/lib/toaster/toastermain/wsgi.py + </literallayout> + Finally, restart Apache to make sure all new configuration + is loaded. + For Ubuntu, Debian, and OpenSUSE use: + <literallayout class='monospaced'> + $ sudo service apache2 restart + </literallayout> + For Fedora and RedHat use: + <literallayout class='monospaced'> + $ sudo service httpd restart + </literallayout> + </para></listitem> + <listitem><para> + Prepare the systemd service to run Toaster builds. + Here is a sample configuration file for the service: + <literallayout class='monospaced'> + [Unit] + Description=Toaster runbuilds + + [Service] + Type=forking + User=toaster + ExecStart=/usr/bin/screen -d -m -S runbuilds /var/www/toaster/poky/bitbake/lib/toaster/runbuilds-service.sh start + ExecStop=/usr/bin/screen -S runbuilds -X quit + WorkingDirectory=/var/www/toaster/poky + + [Install] + WantedBy=multi-user.target + </literallayout> + Prepare the <filename>runbuilds-service.sh</filename> + script that you need to place in the + <filename>/var/www/toaster/poky/bitbake/lib/toaster/</filename> + directory by setting up executable permissions: + <literallayout class='monospaced'> + #!/bin/bash + + #export http_proxy=http://proxy.host.com:8080 + #export https_proxy=http://proxy.host.com:8080 + #export GIT_PROXY_COMMAND=$HOME/bin/gitproxy + + cd ~/poky/ + source ./oe-init-build-env build + source ../bitbake/bin/toaster $1 noweb + [ "$1" == 'start' ] && /bin/bash + </literallayout> + </para></listitem> + <listitem><para> + Run the service: + <literallayout class='monospaced'> + # service runbuilds start + </literallayout> + Since the service is running in a detached screen + session, you can attach to it using this command: + <literallayout class='monospaced'> + $ sudo su - toaster + $ screen -rS runbuilds + </literallayout> + You can detach from the service again using "Ctrl-a" + followed by "d" key combination. + </para></listitem> + </orderedlist> + You can now open up a browser and start using Toaster. + </para> + </section> + </section> + + <section id='using-the-toaster-web-interface'> + <title>Using the Toaster Web Interface</title> + + <para> + The Toaster web interface allows you to do the following: + <itemizedlist> + <listitem><para> + Browse published layers in the + <ulink url='http://layers.openembedded.org'>OpenEmbedded Layer Index</ulink> + that are available for your selected version of the build + system. + </para></listitem> + <listitem><para> + Import your own layers for building. + </para></listitem> + <listitem><para> + Add and remove layers from your configuration. + </para></listitem> + <listitem><para> + Set configuration variables. + </para></listitem> + <listitem><para> + Select a target or multiple targets to build. + </para></listitem> + <listitem><para> + Start your builds. + </para></listitem> + <listitem><para> + See what was built (recipes and packages) and what + packages were installed into your final image. + </para></listitem> + <listitem><para> + Browse the directory structure of your image. + </para></listitem> + <listitem><para> + See the value of all variables in your build configuration, + and which files set each value. + </para></listitem> + <listitem><para> + Examine error, warning and trace messages to aid in + debugging. + </para></listitem> + <listitem><para> + See information about the BitBake tasks executed and + reused during your build, including those that used + shared state. + </para></listitem> + <listitem><para> + See dependency relationships between recipes, packages + and tasks. + </para></listitem> + <listitem><para> + See performance information such as build time, task time, + CPU usage, and disk I/O. + </para></listitem> + </itemizedlist> + </para> + + <section id='web-interface-videos'> + <title>Toaster Web Interface Videos</title> + + <para> + Following are several videos that show how to use the Toaster GUI: + <itemizedlist> + <listitem><para><emphasis>Build Configuration:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=qYgDZ8YzV6w'>video</ulink> + overviews and demonstrates build configuration for Toaster. + </para></listitem> + <listitem><para><emphasis>Build Custom Layers:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=QJzaE_XjX5c'>video</ulink> + shows you how to build custom layers that are used with + Toaster. + </para></listitem> + <listitem><para><emphasis>Toaster Homepage and Table Controls:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=QEARDnrR1Xw'>video</ulink> + goes over the Toaster entry page, and provides + an overview of the data manipulation capabilities of + Toaster, which include search, sorting and filtering by + different criteria. + </para></listitem> + <listitem><para><emphasis>Build Dashboard:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=KKqHYcnp2gE'>video</ulink> + shows you the build dashboard, a page providing an + overview of the information available for a selected build. + </para></listitem> + <listitem><para><emphasis>Image Information:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=XqYGFsmA0Rw'>video</ulink> + walks through the information Toaster provides + about images: packages installed and root file system. + </para></listitem> + <listitem><para><emphasis>Configuration:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=UW-j-T2TzIg'>video</ulink> + provides Toaster build configuration information. + </para></listitem> + <listitem><para><emphasis>Tasks:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=D4-9vGSxQtw'>video</ulink> + shows the information Toaster provides about the + tasks run by the build system. + </para></listitem> + <listitem><para><emphasis>Recipes and Packages Built:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=x-6dx4huNnw'>video</ulink> + shows the information Toaster provides about recipes + and packages built. + </para></listitem> + <listitem><para><emphasis>Performance Data:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=qWGMrJoqusQ'>video</ulink> + shows the build performance data provided by + Toaster. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='a-note-on-the-local-yocto-project-release'> + <title>Additional Information About the Local Yocto Project Release</title> + + <para> + This section only applies if you have set up Toaster + for local development, as explained in the + "<link linkend='starting-toaster-for-local-development'>Starting Toaster for Local Development</link>" + section. + </para> + + <para> + When you create a project in Toaster, you will be asked to + provide a name and to select a Yocto Project release. + One of the release options you will find is called + "Local Yocto Project". + <imagedata fileref="figures/new-project.png" align="center" width="9in" /> + </para> + + <para> + When you select the "Local Yocto Project" release, Toaster + will run your builds using the local Yocto + Project clone you have in your computer: the same clone + you are using to run Toaster. + Unless you manually update + this clone, your builds will always use the same Git revision. + </para> + + <para> + If you select any of the other release options, Toaster + will fetch the tip of your selected release from the upstream + <ulink url='https://git.yoctoproject.org'>Yocto Project repository</ulink> + every time you run a build. + Fetching this tip effectively + means that if your selected release is updated upstream, the + Git revision you are using for your builds will change. + If you are doing development locally, you might not want this + change to happen. + In that case, the "Local Yocto Project" + release might be the right choice. + </para> + + <para> + However, the "Local Yocto Project" release + will not provide you with any compatible layers, other than the + three core layers that come with the Yocto Project: + <itemizedlist> + <listitem><para> + <ulink url='http://layers.openembedded.org/layerindex/branch/master/layer/openembedded-core/'>openembedded-core</ulink> + </para></listitem> + <listitem><para> + <ulink url='http://layers.openembedded.org/layerindex/branch/master/layer/meta-poky/'>meta-poky</ulink> + </para></listitem> + <listitem><para> + <ulink url='http://layers.openembedded.org/layerindex/branch/master/layer/meta-yocto-bsp/'>meta-yocto-bsp</ulink> + </para></listitem> + </itemizedlist> + <imagedata fileref="figures/compatible-layers.png" align="center" width="9in" /> + </para> + + <para> + If you want to build any other layers, you will need to + manually import them into your Toaster project, using the + "Import layer" page. + <imagedata fileref="figures/import-layer.png" align="center" width="9in" /> + </para> + + </section> + + <section id='toaster-web-interface-preferred-version'> + <title>Building a Specific Recipe Given Multiple Versions</title> + + <para> + Occasionally, a layer might provide more than one version of + the same recipe. + For example, the <filename>openembedded-core</filename> layer + provides two versions of the <filename>bash</filename> recipe + (i.e. 3.2.48 and 4.3.30-r0) and two versions of the + <filename>which</filename> recipe (i.e. 2.21 and 2.18). + The following figure shows this exact scenario: + <imagedata fileref="figures/bash-oecore.png" align="center" width="9in" depth="6in" /> + </para> + + <para> + By default, the OpenEmbedded build system builds one of the + two recipes. + For the <filename>bash</filename> case, version 4.3.30-r0 is + built by default. + Unfortunately, Toaster as it exists, is not able to override + the default recipe version. + If you would like to build bash 3.2.48, you need to set the + <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink> + variable. + You can do so from Toaster, using the "Add variable" form, + which is available in the "BitBake variables" page of the + project configuration section as shown in the following screen: + <imagedata fileref="figures/add-variable.png" align="center" width="9in" depth="6in" /> + </para> + + <para> + To specify <filename>bash</filename> 3.2.48 as the version to build, + enter "PREFERRED_VERSION_bash" in the "Variable" field, and "3.2.48" + in the "Value" field. + Next, click the "Add variable" button: + <imagedata fileref="figures/set-variable.png" align="center" width="9in" depth="6in" /> + </para> + + <para> + After clicking the "Add variable" button, the settings for + <filename>PREFERRED_VERSION</filename> are added to the bottom + of the BitBake variables list. + With these settings, the OpenEmbedded build system builds the + desired version of the recipe rather than the default version: + <imagedata fileref="figures/variable-added.png" align="center" width="9in" depth="6in" /> + </para> + </section> + </section> +</chapter> diff --git a/poky/documentation/toaster-manual/toaster-manual-start.xml b/poky/documentation/toaster-manual/toaster-manual-start.xml new file mode 100644 index 000000000..45f604617 --- /dev/null +++ b/poky/documentation/toaster-manual/toaster-manual-start.xml @@ -0,0 +1,115 @@ +<!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-start'> + +<title>Preparing to Use Toaster</title> + + <para> + This chapter describes how you need to prepare your system in order to + use Toaster. + </para> + + <section id='toaster-setting-up-the-basic-system-requirements'> + <title>Setting Up the Basic System Requirements</title> + + <para> + Before you can use Toaster, you need to first set up your + build system to run the Yocto Project. + To do this, follow the instructions in the + "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Preparing the Build Host</ulink>" + section of the Yocto Project Development Tasks + Manual. + For Ubuntu/Debian, you might also need to do an additional install + of pip3. + <literallayout class='monospaced'> + $ sudo apt-get install python3-pip + </literallayout> + </para> + </section> + + <section id='toaster-establishing-toaster-system-dependencies'> + <title>Establishing Toaster System Dependencies</title> + + <para> + Toaster requires extra Python dependencies in order to run. + A Toaster requirements file named + <filename>toaster-requirements.txt</filename> defines the + Python dependencies. + The requirements file is located in the + <filename>bitbake</filename> directory, which is located in the + root directory of the + <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. + </para> + + <section id='toaster-load-packages'> + <title>Install Toaster Packages</title> + + <para> + You need to install the packages that Toaster requires. + Use this command: + <literallayout class='monospaced'> + $ 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 + <filename>$HOME</filename> directory. + The caches is actually located in + <filename>$HOME/.local</filename>. + To see what packages have been installed into your + <filename>$HOME</filename> directory, do the following: + <literallayout class='monospaced'> + $ pip3 list installed --local + </literallayout> + If you need to remove something, the following works: + <literallayout class='monospaced'> + $ pip3 uninstall PackageNameToUninstall + </literallayout> + </para> + </section> + +<!-- Commenting this section out for now in case it needs to be used again. + + <section id='toaster-install-daemon'> + <title>Install <filename>daemon</filename></title> + + <para> + Toaster depends on + <ulink url='http://www.libslack.org/daemon/'><filename>daemon</filename></ulink>. + Depending on your distribution, how you install + <filename>daemon</filename> differs: + <itemizedlist> + <listitem><para><emphasis>Debian-Based Systems:</emphasis> + If you are running a Debian-based distribution, + install <filename>daemon</filename> using the + following command: + <literallayout class='monospaced'> + $ sudo apt-get install daemon + </literallayout> + </para></listitem> + <listitem><para><emphasis>Non-Debian-Based Systems:</emphasis> + If you are not running a Debian-based distribution + (Redhat-based distribution such as Fedora), + you need to download the file relevant to the + architecture and then install + <filename>daemon</filename> manually. + Following are the commands for 64-bit distributions: + <literallayout class='monospaced'> + $ wget http://libslack.org/daemon/download/daemon-0.6.4-1.x86_64.rpm + $ sudo rpm -i daemon-0.6.4-1.x86_64.rpm + </literallayout> + Here are the commands for a 32-bit distribution: + <literallayout class='monospaced'> + $ wget http://libslack.org/daemon/download/daemon-0.6.4-1.i686.rpm + $ sudo rpm -i daemon-0.6.4-1.i686.rpm + </literallayout> + </para></listitem> + </itemizedlist> + </para> + </section> --> + </section> +</chapter> diff --git a/poky/documentation/toaster-manual/toaster-manual-style.css b/poky/documentation/toaster-manual/toaster-manual-style.css new file mode 100644 index 000000000..6d6b9fb65 --- /dev/null +++ b/poky/documentation/toaster-manual/toaster-manual-style.css @@ -0,0 +1,984 @@ +/* + Generic XHTML / DocBook XHTML CSS Stylesheet. + + Browser wrangling and typographic design by + Oyvind Kolas / pippin@gimp.org + + Customised for Poky by + Matthew Allum / mallum@o-hand.com + + Thanks to: + Liam R. E. Quin + William Skaggs + Jakub Steiner + + Structure + --------- + + The stylesheet is divided into the following sections: + + Positioning + Margins, paddings, width, font-size, clearing. + Decorations + Borders, style + Colors + Colors + Graphics + Graphical backgrounds + Nasty IE tweaks + Workarounds needed to make it work in internet explorer, + currently makes the stylesheet non validating, but up until + this point it is validating. + Mozilla extensions + Transparency for footer + Rounded corners on boxes + +*/ + + + /*************** / + / Positioning / +/ ***************/ + +body { + font-family: Verdana, Sans, sans-serif; + + min-width: 640px; + width: 80%; + margin: 0em auto; + padding: 2em 5em 5em 5em; + color: #333; +} + +h1,h2,h3,h4,h5,h6,h7 { + font-family: Arial, Sans; + color: #00557D; + clear: both; +} + +h1 { + font-size: 2em; + text-align: left; + padding: 0em 0em 0em 0em; + margin: 2em 0em 0em 0em; +} + +h2.subtitle { + margin: 0.10em 0em 3.0em 0em; + padding: 0em 0em 0em 0em; + font-size: 1.8em; + padding-left: 20%; + font-weight: normal; + font-style: italic; +} + +h2 { + margin: 2em 0em 0.66em 0em; + padding: 0.5em 0em 0em 0em; + font-size: 1.5em; + font-weight: bold; +} + +h3.subtitle { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; + font-size: 142.14%; + text-align: right; +} + +h3 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 140%; + font-weight: bold; +} + +h4 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 120%; + font-weight: bold; +} + +h5 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +h6 { + margin: 1em 0em 0em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +.authorgroup { + background-color: transparent; + background-repeat: no-repeat; + padding-top: 256px; + background-image: url("figures/toaster-title.png"); + background-position: left top; + margin-top: -256px; + padding-right: 50px; + margin-left: 0px; + text-align: right; + width: 740px; +} + +h3.author { + margin: 0em 0me 0em 0em; + padding: 0em 0em 0em 0em; + font-weight: normal; + font-size: 100%; + color: #333; + clear: both; +} + +.author tt.email { + font-size: 66%; +} + +.titlepage hr { + width: 0em; + clear: both; +} + +.revhistory { + padding-top: 2em; + clear: both; +} + +.toc, +.list-of-tables, +.list-of-examples, +.list-of-figures { + padding: 1.33em 0em 2.5em 0em; + color: #00557D; +} + +.toc p, +.list-of-tables p, +.list-of-figures p, +.list-of-examples p { + padding: 0em 0em 0em 0em; + padding: 0em 0em 0.3em; + margin: 1.5em 0em 0em 0em; +} + +.toc p b, +.list-of-tables p b, +.list-of-figures p b, +.list-of-examples p b{ + font-size: 100.0%; + font-weight: bold; +} + +.toc dl, +.list-of-tables dl, +.list-of-figures dl, +.list-of-examples dl { + margin: 0em 0em 0.5em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dt { + margin: 0em 0em 0em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dd { + margin: 0em 0em 0em 2.6em; + padding: 0em 0em 0em 0em; +} + +div.glossary dl, +div.variablelist dl { +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + font-weight: normal; + width: 20em; + text-align: right; +} + +.variablelist dl dt { + margin-top: 0.5em; +} + +.glossary dl dd, +.variablelist dl dd { + margin-top: -1em; + margin-left: 25.5em; +} + +.glossary dd p, +.variablelist dd p { + margin-top: 0em; + margin-bottom: 1em; +} + + +div.calloutlist table td { + padding: 0em 0em 0em 0em; + margin: 0em 0em 0em 0em; +} + +div.calloutlist table td p { + margin-top: 0em; + margin-bottom: 1em; +} + +div p.copyright { + text-align: left; +} + +div.legalnotice p.legalnotice-title { + margin-bottom: 0em; +} + +p { + line-height: 1.5em; + margin-top: 0em; + +} + +dl { + padding-top: 0em; +} + +hr { + border: solid 1px; +} + + +.mediaobject, +.mediaobjectco { + text-align: center; +} + +img { + border: none; +} + +ul { + padding: 0em 0em 0em 1.5em; +} + +ul li { + padding: 0em 0em 0em 0em; +} + +ul li p { + text-align: left; +} + +table { + width :100%; +} + +th { + padding: 0.25em; + text-align: left; + font-weight: normal; + vertical-align: top; +} + +td { + padding: 0.25em; + vertical-align: top; +} + +p a[id] { + margin: 0px; + padding: 0px; + display: inline; + background-image: none; +} + +a { + text-decoration: underline; + color: #444; +} + +pre { + overflow: auto; +} + +a:hover { + text-decoration: underline; + /*font-weight: bold;*/ +} + +/* This style defines how the permalink character + appears by itself and when hovered over with + the mouse. */ + +[alt='Permalink'] { color: #eee; } +[alt='Permalink']:hover { color: black; } + + +div.informalfigure, +div.informalexample, +div.informaltable, +div.figure, +div.table, +div.example { + margin: 1em 0em; + padding: 1em; + page-break-inside: avoid; +} + + +div.informalfigure p.title b, +div.informalexample p.title b, +div.informaltable p.title b, +div.figure p.title b, +div.example p.title b, +div.table p.title b{ + padding-top: 0em; + margin-top: 0em; + font-size: 100%; + font-weight: normal; +} + +.mediaobject .caption, +.mediaobject .caption p { + text-align: center; + font-size: 80%; + padding-top: 0.5em; + padding-bottom: 0.5em; +} + +.epigraph { + padding-left: 55%; + margin-bottom: 1em; +} + +.epigraph p { + text-align: left; +} + +.epigraph .quote { + font-style: italic; +} +.epigraph .attribution { + font-style: normal; + text-align: right; +} + +span.application { + font-style: italic; +} + +.programlisting { + font-family: monospace; + font-size: 80%; + white-space: pre; + margin: 1.33em 0em; + padding: 1.33em; +} + +.tip, +.warning, +.caution, +.note { + margin-top: 1em; + margin-bottom: 1em; + +} + +/* force full width of table within div */ +.tip table, +.warning table, +.caution table, +.note table { + border: none; + width: 100%; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + padding: 0.8em 0.0em 0.0em 0.0em; + margin : 0em 0em 0em 0em; +} + +.tip p, +.warning p, +.caution p, +.note p { + margin-top: 0.5em; + margin-bottom: 0.5em; + padding-right: 1em; + text-align: left; +} + +.acronym { + text-transform: uppercase; +} + +b.keycap, +.keycap { + padding: 0.09em 0.3em; + margin: 0em; +} + +.itemizedlist li { + clear: none; +} + +.filename { + font-size: medium; + font-family: Courier, monospace; +} + + +div.navheader, div.heading{ + position: absolute; + left: 0em; + top: 0em; + width: 100%; + background-color: #cdf; + width: 100%; +} + +div.navfooter, div.footing{ + position: fixed; + left: 0em; + bottom: 0em; + background-color: #eee; + width: 100%; +} + + +div.navheader td, +div.navfooter td { + font-size: 66%; +} + +div.navheader table th { + /*font-family: Georgia, Times, serif;*/ + /*font-size: x-large;*/ + font-size: 80%; +} + +div.navheader table { + border-left: 0em; + border-right: 0em; + border-top: 0em; + width: 100%; +} + +div.navfooter table { + border-left: 0em; + border-right: 0em; + border-bottom: 0em; + width: 100%; +} + +div.navheader table td a, +div.navfooter table td a { + color: #777; + text-decoration: none; +} + +/* normal text in the footer */ +div.navfooter table td { + color: black; +} + +div.navheader table td a:visited, +div.navfooter table td a:visited { + color: #444; +} + + +/* links in header and footer */ +div.navheader table td a:hover, +div.navfooter table td a:hover { + text-decoration: underline; + background-color: transparent; + color: #33a; +} + +div.navheader hr, +div.navfooter hr { + display: none; +} + + +.qandaset tr.question td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} + +.qandaset tr.answer td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} +.answer td { + padding-bottom: 1.5em; +} + +.emphasis { + font-weight: bold; +} + + + /************* / + / decorations / +/ *************/ + +.titlepage { +} + +.part .title { +} + +.subtitle { + border: none; +} + +/* +h1 { + border: none; +} + +h2 { + border-top: solid 0.2em; + border-bottom: solid 0.06em; +} + +h3 { + border-top: 0em; + border-bottom: solid 0.06em; +} + +h4 { + border: 0em; + border-bottom: solid 0.06em; +} + +h5 { + border: 0em; +} +*/ + +.programlisting { + border: solid 1px; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example { + border: 1px solid; +} + + + +.tip, +.warning, +.caution, +.note { + border: 1px solid; +} + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom: 1px solid; +} + +.question td { + border-top: 1px solid black; +} + +.answer { +} + + +b.keycap, +.keycap { + border: 1px solid; +} + + +div.navheader, div.heading{ + border-bottom: 1px solid; +} + + +div.navfooter, div.footing{ + border-top: 1px solid; +} + + /********* / + / colors / +/ *********/ + +body { + color: #333; + background: white; +} + +a { + background: transparent; +} + +a:hover { + background-color: #dedede; +} + + +h1, +h2, +h3, +h4, +h5, +h6, +h7, +h8 { + background-color: transparent; +} + +hr { + border-color: #aaa; +} + + +.tip, .warning, .caution, .note { + border-color: #fff; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom-color: #fff; +} + + +.warning { + background-color: #f0f0f2; +} + +.caution { + background-color: #f0f0f2; +} + +.tip { + background-color: #f0f0f2; +} + +.note { + background-color: #f0f0f2; +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + color: #044; +} + +div.figure, +div.table, +div.example, +div.informalfigure, +div.informaltable, +div.informalexample { + border-color: #aaa; +} + +pre.programlisting { + color: black; + background-color: #fff; + border-color: #aaa; + border-width: 2px; +} + +.guimenu, +.guilabel, +.guimenuitem { + background-color: #eee; +} + + +b.keycap, +.keycap { + background-color: #eee; + border-color: #999; +} + + +div.navheader { + border-color: black; +} + + +div.navfooter { + border-color: black; +} + + + /*********** / + / graphics / +/ ***********/ + +/* +body { + background-image: url("images/body_bg.jpg"); + background-attachment: fixed; +} + +.navheader, +.note, +.tip { + background-image: url("images/note_bg.jpg"); + background-attachment: fixed; +} + +.warning, +.caution { + background-image: url("images/warning_bg.jpg"); + background-attachment: fixed; +} + +.figure, +.informalfigure, +.example, +.informalexample, +.table, +.informaltable { + background-image: url("images/figure_bg.jpg"); + background-attachment: fixed; +} + +*/ +h1, +h2, +h3, +h4, +h5, +h6, +h7{ +} + +/* +Example of how to stick an image as part of the title. + +div.article .titlepage .title +{ + background-image: url("figures/white-on-black.png"); + background-position: center; + background-repeat: repeat-x; +} +*/ + +div.preface .titlepage .title, +div.colophon .title, +div.chapter .titlepage .title, +div.article .titlepage .title +{ +} + +div.section div.section .titlepage .title, +div.sect2 .titlepage .title { + background: none; +} + + +h1.title { + background-color: transparent; + background-repeat: no-repeat; + height: 256px; + text-indent: -9000px; + overflow:hidden; +} + +h2.subtitle { + background-color: transparent; + text-indent: -9000px; + overflow:hidden; + width: 0px; + display: none; +} + + /*************************************** / + / pippin.gimp.org specific alterations / +/ ***************************************/ + +/* +div.heading, div.navheader { + color: #777; + font-size: 80%; + padding: 0; + margin: 0; + text-align: left; + position: absolute; + top: 0px; + left: 0px; + width: 100%; + height: 50px; + background: url('/gfx/heading_bg.png') transparent; + background-repeat: repeat-x; + background-attachment: fixed; + border: none; +} + +div.heading a { + color: #444; +} + +div.footing, div.navfooter { + border: none; + color: #ddd; + font-size: 80%; + text-align:right; + + width: 100%; + padding-top: 10px; + position: absolute; + bottom: 0px; + left: 0px; + + background: url('/gfx/footing_bg.png') transparent; +} +*/ + + + + /****************** / + / nasty ie tweaks / +/ ******************/ + +/* +div.heading, div.navheader { + width:expression(document.body.clientWidth + "px"); +} + +div.footing, div.navfooter { + width:expression(document.body.clientWidth + "px"); + margin-left:expression("-5em"); +} +body { + padding:expression("4em 5em 0em 5em"); +} +*/ + + /**************************************** / + / mozilla vendor specific css extensions / +/ ****************************************/ +/* +div.navfooter, div.footing{ + -moz-opacity: 0.8em; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example, +.tip, +.warning, +.caution, +.note { + -moz-border-radius: 0.5em; +} + +b.keycap, +.keycap { + -moz-border-radius: 0.3em; +} +*/ + +table tr td table tr td { + display: none; +} + + +hr { + display: none; +} + +table { + border: 0em; +} + + .photo { + float: right; + margin-left: 1.5em; + margin-bottom: 1.5em; + margin-top: 0em; + max-width: 17em; + border: 1px solid gray; + padding: 3px; + background: white; +} + .seperator { + padding-top: 2em; + clear: both; + } + + #validators { + margin-top: 5em; + text-align: right; + color: #777; + } + @media print { + body { + font-size: 8pt; + } + .noprint { + display: none; + } + } + + +.tip, +.note { + background: #f0f0f2; + color: #333; + padding: 20px; + margin: 20px; +} + +.tip h3, +.note h3 { + padding: 0em; + margin: 0em; + font-size: 2em; + font-weight: bold; + color: #333; +} + +.tip a, +.note a { + color: #333; + text-decoration: underline; +} + +.footnote { + font-size: small; + color: #333; +} + +/* Changes the announcement text */ +.tip h3, +.warning h3, +.caution h3, +.note h3 { + font-size:large; + color: #00557D; +} diff --git a/poky/documentation/toaster-manual/toaster-manual.xml b/poky/documentation/toaster-manual/toaster-manual.xml new file mode 100644 index 000000000..188874488 --- /dev/null +++ b/poky/documentation/toaster-manual/toaster-manual.xml @@ -0,0 +1,137 @@ +<!DOCTYPE book 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; ] > + +<book id='toaster-manual' lang='en' + xmlns:xi="http://www.w3.org/2003/XInclude" + xmlns="http://docbook.org/ns/docbook" + > + <bookinfo> + + <mediaobject> + <imageobject> + <imagedata fileref='figures/toaster-title.png' + format='SVG' + align='left' scalefit='1' width='100%'/> + </imageobject> + </mediaobject> + + <title> + Toaster User Manual + </title> + + <authorgroup> + <author> + <firstname>Kristi</firstname> <surname>Rifenbark</surname> + <affiliation> + <orgname>Scotty's Documentation Services, INC</orgname> + </affiliation> + <email>kristi@buzzcollectivemarketing.com</email> + </author> + </authorgroup> + + <revhistory> + <revision> + <revnumber>1.8</revnumber> + <date>April 2015</date> + <revremark>Released with the Yocto Project 1.8 Release.</revremark> + </revision> + <revision> + <revnumber>2.0</revnumber> + <date>October 2015</date> + <revremark>Released with the Yocto Project 2.0 Release.</revremark> + </revision> + <revision> + <revnumber>2.1</revnumber> + <date>April 2016</date> + <revremark>Released with the Yocto Project 2.1 Release.</revremark> + </revision> + <revision> + <revnumber>2.2</revnumber> + <date>October 2016</date> + <revremark>Released with the Yocto Project 2.2 Release.</revremark> + </revision> + <revision> + <revnumber>2.3</revnumber> + <date>May 2017</date> + <revremark>Released with the Yocto Project 2.3 Release.</revremark> + </revision> + <revision> + <revnumber>2.4</revnumber> + <date>October 2017</date> + <revremark>Released with the Yocto Project 2.4 Release.</revremark> + </revision> + <revision> + <revnumber>2.5</revnumber> + <date>May 2018</date> + <revremark>Released with the Yocto Project 2.5 Release.</revremark> + </revision> + </revhistory> + + <copyright> + <year>©RIGHT_YEAR;</year> + <holder>Linux Foundation</holder> + </copyright> + + <legalnotice> + <para> + Permission is granted to copy, distribute and/or modify this document under + the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. + </para> + <note><title>Manual Notes</title> + <itemizedlist> + <listitem><para> + 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, go to the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink> + and select the manual from that site. + Manuals from the site are more up-to-date than manuals + derived from the Yocto Project released TAR files. + </para></listitem> + <listitem><para> + If you located this manual through a web search, the + version of the manual might not be the one you want + (e.g. the search might have returned a manual much + older than the Yocto Project version with which you + are working). + You can see all Yocto Project major releases by + visiting the + <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink> + page. + If you need a version of this manual for a different + Yocto Project release, visit the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink> + and select the manual set by using the + "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE" + pull-down menus. + </para></listitem> + <listitem><para> + 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> + + </legalnotice> + + </bookinfo> + + <xi:include href="toaster-manual-intro.xml"/> + + <xi:include href="toaster-manual-start.xml"/> + + <xi:include href="toaster-manual-setup-and-use.xml"/> + + <xi:include href="toaster-manual-reference.xml"/> + +</book> +<!-- +vim: expandtab tw=80 ts=4 +--> |
