diff options
Diffstat (limited to 'documentation/toaster-manual/toaster-manual-intro.xml')
| -rw-r--r-- | documentation/toaster-manual/toaster-manual-intro.xml | 224 |
1 files changed, 131 insertions, 93 deletions
diff --git a/documentation/toaster-manual/toaster-manual-intro.xml b/documentation/toaster-manual/toaster-manual-intro.xml index 378f33420c..ad9e08b50d 100644 --- a/documentation/toaster-manual/toaster-manual-intro.xml +++ b/documentation/toaster-manual/toaster-manual-intro.xml @@ -6,95 +6,12 @@ <title>Introduction</title> <para> - Toaster is web interface to the OpenEmbedded build system, which uses - BitBake. - The interface allows you to access a datastore that retains build - information and report out on the information. - </para> -<!--THE FOLLOWING IS DETAIL THAT I THINK BELEN WANTED OUT FOR THE MOMENT - The interface is based on a Representational State Transfer - (REST) API that queries for and returns build information using - <filename>GET</filename> and <filename>JSON</filename>. - These types of search operations retrieve sets of objects from - a datastore used to collect build information. - The results contain all the data for the objects being returned. - You can order the results of the search by key and the search - parameters are consistent for all object types. - </para> ---> - - <para> - You can use Toaster in several different modes: - <itemizedlist> - <listitem><para><emphasis>Analysis Mode:</emphasis> - In this mode, you can record builds and statistics. - In Analysis Mode, you have direct access to the - <filename>bitbake</filename> command, which you use to build - images.</para> - <para>Analysis Mode requires you to have first started - Toaster and then to initiate your build using the - <filename>bitbake</filename> command from the shell. - Toaster must be started before the build or it will not - collect build data. - </para></listitem> - <listitem><para><emphasis>Build Mode:</emphasis> - In this mode, Toaster handles the build configuration GUI - (through project pages) and build scheduling and execution. - In this mode, all your interaction with the build system - happens through the web interface. - You do not have direct access to the - <filename>bitbake</filename> command.</para> - <para>Using this mode, you configure and start your builds - with Toaster's GUI. - Each configuration is a project, which requires version and - build system selection. - As shipped, Toaster supports the Yocto Project releases - 1.8 and beyond. - Aside from these supported releases, you can also select - the "Local Yocto Project", which allows you to use your - local clone of the Yocto Project - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> - (e.g. <filename>poky</filename>).</para> - <para>Build Mode also works two separate ways: locally and - remotely. - While you can use Build Mode locally, it is best to use - Toaster's Build Mode through a hosted service where it can - shared by multiple user. - </para></listitem> - </itemizedlist> - </para> - - <para> - Using Toaster, you can do the following: - <note><title>REVIEWER NOTE</title> - Belen suggested we split this list out into things that - Analysis Mode and Build Mode can do. - Also, we can structure the lists so the Build Mode list - leverages off what is listed for Analysis Mode. - I do not know the information for the complete lists. - Someone needs to help me out here. - For now, I am leaving the list as follows and will need some - information. - </note> - <itemizedlist> - <listitem><para> - See information about the tasks executed - and reused during the build. - </para></listitem> - <listitem><para> - See what is built (recipes and - packages) and what packages were installed into the final - image. - </para></listitem> - <listitem><para> - See performance-related information such - as build time, CPU usage, and disk I/O. - </para></listitem> - <listitem><para> - Examine error, warning and trace messages - to aid in debugging. - </para></listitem> - </itemizedlist> + 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> <note> @@ -116,10 +33,131 @@ </para> </note> - <para> - The remainder of this manual describes what you need to have in - place to use Toaster, how to start it, use it, and stop it. - </para> + <section id='intro-modes'> + <title>Toaster Operational Modes</title> + + <para> + You can use Toaster in Analysis Mode or Build Mode: + <itemizedlist> + <listitem><para><emphasis>Analysis Mode:</emphasis> + In Analysis Mode, you can record builds and statistics. + In this Mode, you directly access the + <filename>bitbake</filename> command, which you then use to + build images.</para> + <para>Analysis Mode requires you to have first started + Toaster and then to initiate your build using the + <filename>bitbake</filename> command from the shell. + Toaster must be started before the build or it will not + collect build data.</para> + <para>Toaster has the following capabilities in + Analysis Mode: + <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> + <listitem><para><emphasis>Build Mode:</emphasis> + In Build Mode, Toaster handles the build configuration, + scheduling and execution. + In this mode, all your interaction with the build system + happens through the web interface. + You do not have direct access to the + <filename>bitbake</filename> command.</para> + <para>Using this mode, you configure and start your builds + within Toaster's GUI. + Each project can be configured for a specific version + of the build system. + As shipped, Toaster supports Yocto Project Releases 1.7 and + beyond.</para> + <para>Toaster has all the same capabilities in Build Mode + as it does in Analysis Mode plus the following: + <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> + 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> + </para></listitem> + </itemizedlist> + </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. + Regardless of how you set up Toaster, both Analysis and Build + Modes are available. + </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 |