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.xml289
1 files changed, 0 insertions, 289 deletions
diff --git a/documentation/toaster-manual/toaster-manual-intro.xml b/documentation/toaster-manual/toaster-manual-intro.xml
index 86acac2508..36c3b6bdc0 100644
--- a/documentation/toaster-manual/toaster-manual-intro.xml
+++ b/documentation/toaster-manual/toaster-manual-intro.xml
@@ -93,295 +93,6 @@
93 <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink> 93 <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink>
94 Wiki page. 94 Wiki page.
95 </para> 95 </para>
96
97 <section id='toaster-manual-dev-notes'>
98 <title>Manual development notes:</title>
99
100 <itemizedlist>
101 <listitem><para>
102 Need chapter on getting your system ready for Toaster and
103 installing Toaster.
104 Probably should consider some past releases of YP in here
105 one way or another.
106 </para></listitem>
107 <listitem><para>
108 Need a chapter on configuring Toaster.
109 </para></listitem>
110 <listitem><para>
111 Need a chapter on setting up instances of Toaster.
112 We will want two sub-sections here: 1) a local instance, and
113 2) a production instance.
114 </para></listitem>
115 <listitem><para>
116 Need a chapter on starting and stopping Toaster.
117 Need to cover starting in managed mode here.
118 </para></listitem>
119 <listitem><para>
120 We need a chapter on the user interface.
121 Need to decide if we want to stick with the slick videos that
122 currently live on the YP site.
123 Pros for this are they are cool and convey information nicely.
124 Cons are they are release dependent and would be high
125 maintenance over the long haul.
126 Standard practices usually dictate going with a method that
127 is as divorced as possible from video shots and images of
128 actual GUIs for a product.
129 Rationale is that a person can invoke the tool and see the
130 actual GUI as they read along with any documentation.
131 Changing textual descriptions is a lot less headache than
132 updating videos and screenshots.
133 </para></listitem>
134 <listitem><para>
135 We need a chapter on Toaster's build functionality.
136 My understanding is that this is the new thing for 1.8.
137 Here are some topics identified that would translate into
138 individual sections:
139 <itemizedlist>
140 <listitem><para>
141 Using Virtualenv
142 </para></listitem>
143 <listitem><para>
144 manage.py commands
145 </para></listitem>
146 <listitem><para>
147 Custom layer index
148 </para></listitem>
149 </itemizedlist>
150 I lifted these from the
151 <ulink url='https://wiki.yoctoproject.org/wiki/Toaster'>wiki</ulink>.
152 Some items in the list, such as configuration and setting
153 up instances of Toaster, will be covered in different
154 chapters.
155 </para></listitem>
156 <listitem><para>
157 Could think about a chapter on using Toaster to debug common
158 issues such as failed dependencies and whatever would be
159 something people might run into.
160 </para></listitem>
161 <listitem><para>
162 Could maybe include a chapter on the database and other
163 "under-the-cover" stuff that might be useful.
164 I am not sure if any of it would be but it is a thought.
165 </para></listitem>
166 </itemizedlist>
167 </section>
168
169
170
171
172<!--
173 <section id="examining-builds-using-toaster">
174 <title>Examining Builds Using the Toaster API</title>
175
176 <para>
177 Toaster is an Application Programming Interface (API) and
178 web-based interface to the OpenEmbedded build system, which uses
179 BitBake.
180 Both interfaces are based on a Representational State Transfer
181 (REST) API that queries for and returns build information using
182 <filename>GET</filename> and <filename>JSON</filename>.
183 These types of search operations retrieve sets of objects from
184 a datastore used to collect build information.
185 The results contain all the data for the objects being returned.
186 You can order the results of the search by key and the search
187 parameters are consistent for all object types.
188 </para>
189
190 <para>
191 Using the interfaces you can do the following:
192 <itemizedlist>
193 <listitem><para>See information about the tasks executed
194 and reused during the build.</para></listitem>
195 <listitem><para>See what is built (recipes and
196 packages) and what packages were installed into the final
197 image.</para></listitem>
198 <listitem><para>See performance-related information such
199 as build time, CPU usage, and disk I/O.</para></listitem>
200 <listitem><para>Examine error, warning and trace messages
201 to aid in debugging.</para></listitem>
202 </itemizedlist>
203 </para>
204
205 <note>
206 <para>This release of Toaster provides you with information
207 about a BitBake run.
208 The tool does not allow you to configure and launch a build.
209 However, future development includes plans to integrate the
210 configuration and build launching capabilities of
211 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>.
212 </para>
213 <para>For more information on using Hob to build an image,
214 see the
215 "<link linkend='image-development-using-hob'>Image Development Using Hob</link>"
216 section.</para>
217 </note>
218
219 <para>
220 The remainder of this section describes what you need to have in
221 place to use Toaster, how to start it, use it, and stop it.
222 For additional information on installing and running Toaster, see the
223 "<ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Installation_and_Running'>Installation and Running</ulink>"
224 section of the "Toaster" wiki page.
225 For complete information on the API and its search operation
226 URI, parameters, and responses, see the
227 <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink>
228 Wiki page.
229 </para>
230
231 <section id='starting-toaster'>
232 <title>Starting Toaster</title>
233
234 <para>
235 Getting set up to use and start Toaster is simple.
236 First, be sure you have met the following requirements:
237 <itemizedlist>
238 <listitem><para>You have set up your
239 <link linkend='source-directory'>Source Directory</link>
240 by cloning the upstream <filename>poky</filename>
241 repository.
242 See the
243 <link linkend='local-yp-release'>Yocto Project Release</link>
244 item for information on how to set up the Source
245 Directory.</para></listitem>
246 <listitem><para>Be sure your build machine has
247 <ulink url='http://en.wikipedia.org/wiki/Django_%28web_framework%29'>Django</ulink>
248 version 1.5 installed.</para></listitem>
249 <listitem><para>Make sure that port 8000 and 8200 are
250 free (i.e. they have no servers on them).
251 </para></listitem>
252 </itemizedlist>
253 </para>
254
255 <para>
256 Once you have met the requirements, follow these steps to
257 start Toaster running in the background of your shell:
258 <orderedlist>
259 <listitem><para><emphasis>Set up your build environment:</emphasis>
260 Source a build environment script (i.e.
261 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
262 or
263 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
264 </para></listitem>
265 <listitem><para><emphasis>Start Toaster:</emphasis>
266 Start the Toaster service using this
267 command from within your
268 <link linkend='build-directory'>Build Directory</link>:
269 <literallayout class='monospaced'>
270 $ source toaster start
271 </literallayout></para></listitem>
272 <note>
273 The Toaster must be started and running in order
274 for it to collect data.
275 </note>
276 </orderedlist>
277 </para>
278
279 <para>
280 When Toaster starts, it creates some additional files in your
281 Build Directory.
282 Deleting these files will cause you to lose data or interrupt
283 Toaster:
284 <itemizedlist>
285 <listitem><para><emphasis><filename>toaster.sqlite</filename>:</emphasis>
286 Toaster's database file.</para></listitem>
287 <listitem><para><emphasis><filename>toaster_web.log</filename>:</emphasis>
288 The log file of the web server.</para></listitem>
289 <listitem><para><emphasis><filename>toaster_ui.log</filename>:</emphasis>
290 The log file of the user interface component.
291 </para></listitem>
292 <listitem><para><emphasis><filename>toastermain.pid</filename>:</emphasis>
293 The PID of the web server.</para></listitem>
294 <listitem><para><emphasis><filename>toasterui.pid</filename>:</emphasis>
295 The PID of the DSI data bridge.</para></listitem>
296 <listitem><para><emphasis><filename>bitbake-cookerdaemon.log</filename>:</emphasis>
297 The BitBake server's log file.</para></listitem>
298 </itemizedlist>
299 </para>
300 </section>
301
302 <section id='using-toaster'>
303 <title>Using Toaster</title>
304
305 <para>
306 Once Toaster is running, it logs information for any BitBake
307 run from your Build Directory.
308 This logging is automatic.
309 All you need to do is access and use the information.
310 </para>
311
312 <para>
313 You access the information one of two ways:
314 <itemizedlist>
315 <listitem><para>Open a Browser and enter
316 <filename>http://localhost:8000</filename>
317 for the URL.
318 </para></listitem>
319 <listitem><para>Use the <filename>xdg-open</filename>
320 tool from the shell and pass it the same URL.
321 </para></listitem>
322 </itemizedlist>
323 Either method opens the home page for the Toaster interface.
324 </para>
325
326 <note><title>Notes</title>
327 <itemizedlist>
328 <listitem><para>
329 For information on how to delete information from the
330 Toaster database, see the
331 <ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Deleting_a_Build_from_the_Toaster_Database'>Deleting a Build from the Toaster Database</ulink>
332 wiki page.
333 </para></listitem>
334 <listitem><para>
335 For information on how to set up an instance of Toaster
336 on a remote host, see the
337 <ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Setting_up_a_Toaster_Instance_on_a_Remote_Host'>Setting Up a Toaster Instance on a Remote Host</ulink>
338 wiki page.
339 </para></listitem>
340 </itemizedlist>
341 </note>
342 </section>
343
344 <section id='examining-toaster-data'>
345 <title>Examining Toaster Data</title>
346
347 <para>
348 The Toaster database is persistent regardless of whether you
349 start or stop the service.
350 </para>
351
352 <para>
353 Toaster's interface shows you a list of builds
354 (successful and unsuccessful) for which it has data.
355 You can click on any build to see related information.
356 This information includes configuration details, information
357 about tasks, all recipes and packages built and their
358 dependencies, packages and their directory structure as
359 installed in your final image,
360 execution time, CPU usage and disk I/O per task.
361 </para>
362
363 <para>
364 For details on the interface, see the
365 <ulink url='https://www.yoctoproject.org/documentation/toaster-manual'>Toaster Manual</ulink>.
366 </para>
367 </section>
368
369 <section id='stopping-toaster'>
370 <title>Stopping Toaster</title>
371
372 <para>
373 Stop the Toaster service with the following command
374 from with the
375 <link linkend='build-directory'>Build Directory</link>:
376 <literallayout class='monospaced'>
377 $ source toaster stop
378 </literallayout>
379 The service stops but the Toaster database remains persistent.
380 </para>
381 </section>
382 </section>
383-->
384
385</chapter> 96</chapter>
386<!-- 97<!--
387vim: expandtab tw=80 ts=4 98vim: expandtab tw=80 ts=4
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-16 07:56:36 +0000