summaryrefslogtreecommitdiffstats
path: root/documentation/toaster-manual/toaster-manual-intro.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/toaster-manual/toaster-manual-intro.xml')
-rw-r--r--documentation/toaster-manual/toaster-manual-intro.xml224
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 @@
6<title>Introduction</title> 6<title>Introduction</title>
7 7
8 <para> 8 <para>
9 Toaster is web interface to the OpenEmbedded build system, which uses 9 Toaster is a web interface to the Yocto Project's
10 BitBake. 10 <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.
11 The interface allows you to access a datastore that retains build 11 The interface enables you to configure and run your builds.
12 information and report out on the information. 12 Information about builds is collected and stored in a database.
13 </para> 13 You can use Toaster to configure and start builds on multiple
14<!--THE FOLLOWING IS DETAIL THAT I THINK BELEN WANTED OUT FOR THE MOMENT 14 remote build servers.
15 The interface is based on a Representational State Transfer
16 (REST) API that queries for and returns build information using
17 <filename>GET</filename> and <filename>JSON</filename>.
18 These types of search operations retrieve sets of objects from
19 a datastore used to collect build information.
20 The results contain all the data for the objects being returned.
21 You can order the results of the search by key and the search
22 parameters are consistent for all object types.
23 </para>
24-->
25
26 <para>
27 You can use Toaster in several different modes:
28 <itemizedlist>
29 <listitem><para><emphasis>Analysis Mode:</emphasis>
30 In this mode, you can record builds and statistics.
31 In Analysis Mode, you have direct access to the
32 <filename>bitbake</filename> command, which you use to build
33 images.</para>
34 <para>Analysis Mode requires you to have first started
35 Toaster and then to initiate your build using the
36 <filename>bitbake</filename> command from the shell.
37 Toaster must be started before the build or it will not
38 collect build data.
39 </para></listitem>
40 <listitem><para><emphasis>Build Mode:</emphasis>
41 In this mode, Toaster handles the build configuration GUI
42 (through project pages) and build scheduling and execution.
43 In this mode, all your interaction with the build system
44 happens through the web interface.
45 You do not have direct access to the
46 <filename>bitbake</filename> command.</para>
47 <para>Using this mode, you configure and start your builds
48 with Toaster's GUI.
49 Each configuration is a project, which requires version and
50 build system selection.
51 As shipped, Toaster supports the Yocto Project releases
52 1.8 and beyond.
53 Aside from these supported releases, you can also select
54 the "Local Yocto Project", which allows you to use your
55 local clone of the Yocto Project
56 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
57 (e.g. <filename>poky</filename>).</para>
58 <para>Build Mode also works two separate ways: locally and
59 remotely.
60 While you can use Build Mode locally, it is best to use
61 Toaster's Build Mode through a hosted service where it can
62 shared by multiple user.
63 </para></listitem>
64 </itemizedlist>
65 </para>
66
67 <para>
68 Using Toaster, you can do the following:
69 <note><title>REVIEWER NOTE</title>
70 Belen suggested we split this list out into things that
71 Analysis Mode and Build Mode can do.
72 Also, we can structure the lists so the Build Mode list
73 leverages off what is listed for Analysis Mode.
74 I do not know the information for the complete lists.
75 Someone needs to help me out here.
76 For now, I am leaving the list as follows and will need some
77 information.
78 </note>
79 <itemizedlist>
80 <listitem><para>
81 See information about the tasks executed
82 and reused during the build.
83 </para></listitem>
84 <listitem><para>
85 See what is built (recipes and
86 packages) and what packages were installed into the final
87 image.
88 </para></listitem>
89 <listitem><para>
90 See performance-related information such
91 as build time, CPU usage, and disk I/O.
92 </para></listitem>
93 <listitem><para>
94 Examine error, warning and trace messages
95 to aid in debugging.
96 </para></listitem>
97 </itemizedlist>
98 </para> 15 </para>
99 16
100 <note> 17 <note>
@@ -116,10 +33,131 @@
116 </para> 33 </para>
117 </note> 34 </note>
118 35
119 <para> 36 <section id='intro-modes'>
120 The remainder of this manual describes what you need to have in 37 <title>Toaster Operational Modes</title>
121 place to use Toaster, how to start it, use it, and stop it. 38
122 </para> 39 <para>
40 You can use Toaster in Analysis Mode or Build Mode:
41 <itemizedlist>
42 <listitem><para><emphasis>Analysis Mode:</emphasis>
43 In Analysis Mode, you can record builds and statistics.
44 In this Mode, you directly access the
45 <filename>bitbake</filename> command, which you then use to
46 build images.</para>
47 <para>Analysis Mode requires you to have first started
48 Toaster and then to initiate your build using the
49 <filename>bitbake</filename> command from the shell.
50 Toaster must be started before the build or it will not
51 collect build data.</para>
52 <para>Toaster has the following capabilities in
53 Analysis Mode:
54 <itemizedlist>
55 <listitem><para>
56 See what was built (recipes and packages) and what
57 packages were installed into your final image.
58 </para></listitem>
59 <listitem><para>
60 Browse the directory structure of your image.
61 </para></listitem>
62 <listitem><para>
63 See the value of all variables in your build
64 configuration, and which files set each value.
65 </para></listitem>
66 <listitem><para>
67 Examine error, warning and trace messages to aid
68 in debugging.
69 </para></listitem>
70 <listitem><para>
71 See information about the BitBake tasks executed
72 and reused during your build, including those that
73 used shared state.
74 </para></listitem>
75 <listitem><para>
76 See dependency relationships between recipes,
77 packages and tasks
78 </para></listitem>
79 <listitem><para>
80 See performance information such as build time,
81 task time, CPU usage, and disk I/O.
82 </para></listitem>
83 </itemizedlist>
84 </para></listitem>
85 <listitem><para><emphasis>Build Mode:</emphasis>
86 In Build Mode, Toaster handles the build configuration,
87 scheduling and execution.
88 In this mode, all your interaction with the build system
89 happens through the web interface.
90 You do not have direct access to the
91 <filename>bitbake</filename> command.</para>
92 <para>Using this mode, you configure and start your builds
93 within Toaster's GUI.
94 Each project can be configured for a specific version
95 of the build system.
96 As shipped, Toaster supports Yocto Project Releases 1.7 and
97 beyond.</para>
98 <para>Toaster has all the same capabilities in Build Mode
99 as it does in Analysis Mode plus the following:
100 <itemizedlist>
101 <listitem><para>
102 Browse layers listed in the various
103 <link linkend='layer-source'>layer sources</link>
104 that are available in your project (e.g. the
105 OpenEmbedded Metadata Index at
106 <ulink url='http://layers.openembedded.org/layerindex/'></ulink>).
107 </para></listitem>
108 <listitem><para>
109 Import your own layers for building.
110 </para></listitem>
111 <listitem><para>
112 Add and remove layers from your configuration.
113 </para></listitem>
114 <listitem><para>
115 Set configuration variables.
116 </para></listitem>
117 <listitem><para>
118 Select a target or multiple targets to build.
119 </para></listitem>
120 <listitem><para>
121 Start your builds.
122 </para></listitem>
123 </itemizedlist>
124 </para></listitem>
125 </itemizedlist>
126 </para>
127 </section>
128
129 <section id='toaster-installation-options'>
130 <title>Installation Options</title>
131
132 <para>
133 You can set Toaster up to run as a local instance or as a shared
134 hosted service.
135 Regardless of how you set up Toaster, both Analysis and Build
136 Modes are available.
137 </para>
138
139 <para>
140 When Toaster is set up as a local instance, all the components
141 reside on a single build host.
142 Fundamentally, a local instance of Toaster is suited for a single
143 user developing on a single build host.
144 </para>
145
146 <para>
147 <imagedata fileref="figures/simple-configuration.png" align="center" width="6in" depth="1.5in" />
148 </para>
149
150 <para>
151 Toaster as a hosted service is suited for multiple users
152 developing across several build hosts.
153 When Toaster is set up as a hosted service, its components can
154 be spread across several machines:
155 </para>
156
157 <para>
158 <imagedata fileref="figures/hosted-service.png" align="center" width="6in" depth="3.5in" />
159 </para>
160 </section>
123 161
124<!--THIS EXTRA INFORMATION PROBABLY WILL GO AWAY 162<!--THIS EXTRA INFORMATION PROBABLY WILL GO AWAY
125 For additional information on installing and running Toaster, see the 163 For additional information on installing and running Toaster, see the
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-01-13 11:38:08 +0000