blob: e84964c4e1a70361c3dcec25ed16a3dd502c17dc [file] [log] [blame]
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='toaster-manual-intro'>
6<title>Introduction</title>
7
8 <para>
9 Toaster is a web interface to the Yocto Project's
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011 The interface enables you to configure and run your builds.
12 Information about builds is collected and stored in a database.
13 You can use Toaster to configure and start builds on multiple
14 remote build servers.
15 </para>
16
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050017 <section id='intro-features'>
18 <title>Toaster Features</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050019
20 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050021 Toaster allows you to configure and run builds, and it
22 provides extensive information about the build process.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050023 <itemizedlist>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050024 <listitem><para id='toaster-build-features'>
25 <emphasis>Configure and Run Builds:</emphasis>
26 You can use the Toaster web interface to configure and
27 start your builds.
28 Builds started using the Toaster web interface are
29 organized into projects.
30 When you create a project, you are asked to select a
31 release, or version of the build system you want to
32 use for the project builds.
33 As shipped, Toaster supports Yocto Project releases 1.8
34 and beyond.
35 With the Toaster web interface, you can:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050036 <itemizedlist>
37 <listitem><para>
38 Browse layers listed in the various
39 <link linkend='layer-source'>layer sources</link>
40 that are available in your project (e.g. the
Brad Bishop316dfdd2018-06-25 12:45:53 -040041 OpenEmbedded Layer Index at
Patrick Williamsc124f4f2015-09-15 14:41:29 -050042 <ulink url='http://layers.openembedded.org/layerindex/'></ulink>).
43 </para></listitem>
44 <listitem><para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050045 Browse images, recipes, and machines provided by
46 those layers.
47 </para></listitem>
48 <listitem><para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050049 Import your own layers for building.
50 </para></listitem>
51 <listitem><para>
52 Add and remove layers from your configuration.
53 </para></listitem>
54 <listitem><para>
55 Set configuration variables.
56 </para></listitem>
57 <listitem><para>
58 Select a target or multiple targets to build.
59 </para></listitem>
60 <listitem><para>
61 Start your builds.
62 </para></listitem>
63 </itemizedlist>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050064 Toaster also allows you to configure and run your builds
65 from the command line, and switch between the command line and
66 the web interface at any time.
67 Builds started from the command line appear within a special
68 Toaster project called "Command line builds".
69 </para></listitem>
70 <listitem><para id='toaster-analysis-features'>
71 <emphasis>Information About the Build Process:</emphasis>
72 Toaster also records extensive information about your builds.
73 Toaster collects data for builds you start from the web
74 interface and from the command line as long as Toaster
75 is running.
76 <note>
77 You must start Toaster before the build or it will not
78 collect build data.
79 </note></para>
80 <para>With Toaster you can:
81 <itemizedlist>
82 <listitem><para>
83 See what was built (recipes and packages) and what
84 packages were installed into your final image.
85 </para></listitem>
86 <listitem><para>
87 Browse the directory structure of your image.
88 </para></listitem>
89 <listitem><para>
90 See the value of all variables in your build
91 configuration, and which files set each value.
92 </para></listitem>
93 <listitem><para>
94 Examine error, warning, and trace messages to aid
95 in debugging.
96 </para></listitem>
97 <listitem><para>
98 See information about the BitBake tasks executed
99 and reused during your build, including those that
100 used shared state.
101 </para></listitem>
102 <listitem><para>
103 See dependency relationships between recipes,
104 packages, and tasks.
105 </para></listitem>
106 <listitem><para>
107 See performance information such as build time,
108 task time, CPU usage, and disk I/O.
109 </para></listitem>
110 </itemizedlist>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500111 </para></listitem>
112 </itemizedlist>
113 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600114
115 <para>
116 For an overview of Toaster shipped with the Yocto Project &DISTRO;
117 Release, see the
118 "<ulink url='https://youtu.be/BlXdOYLgPxA'>Toaster - Yocto Project 2.2</ulink>"
119 video.
120 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500121 </section>
122
123 <section id='toaster-installation-options'>
124 <title>Installation Options</title>
125
126 <para>
127 You can set Toaster up to run as a local instance or as a shared
128 hosted service.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500129 </para>
130
131 <para>
132 When Toaster is set up as a local instance, all the components
133 reside on a single build host.
134 Fundamentally, a local instance of Toaster is suited for a single
135 user developing on a single build host.
136 </para>
137
138 <para>
139 <imagedata fileref="figures/simple-configuration.png" align="center" width="6in" depth="1.5in" />
140 </para>
141
142 <para>
143 Toaster as a hosted service is suited for multiple users
144 developing across several build hosts.
145 When Toaster is set up as a hosted service, its components can
146 be spread across several machines:
147 </para>
148
149 <para>
150 <imagedata fileref="figures/hosted-service.png" align="center" width="6in" depth="3.5in" />
151 </para>
152 </section>
153
154<!--THIS EXTRA INFORMATION PROBABLY WILL GO AWAY
155 For additional information on installing and running Toaster, see the
156 "<ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Installation_and_Running'>Installation and Running</ulink>"
157 section of the "Toaster" wiki page.
158 For complete information on the API and its search operation
159 URI, parameters, and responses, see the
160 <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink>
161 Wiki page.
162 </para>
163-->
164</chapter>