import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-intro.xml

<!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_DEV_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 Metadata 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>