summaryrefslogtreecommitdiffstats
path: root/documentation/toaster-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/toaster-manual')
-rw-r--r--documentation/toaster-manual/toaster-manual-intro.xml357
1 files changed, 356 insertions, 1 deletions
diff --git a/documentation/toaster-manual/toaster-manual-intro.xml b/documentation/toaster-manual/toaster-manual-intro.xml
index fc7f31c30b..043783e01a 100644
--- a/documentation/toaster-manual/toaster-manual-intro.xml
+++ b/documentation/toaster-manual/toaster-manual-intro.xml
@@ -6,9 +6,364 @@
6<title>Introduction</title> 6<title>Introduction</title>
7 7
8 <para> 8 <para>
9 Placeholder text 9 Toaster is an Application Programming Interface (API) and
10 web-based interface to the OpenEmbedded build system, which uses
11 BitBake.
12 Both interfaces are based on a Representational State Transfer
13 (REST) API that queries for and returns build information using
14 <filename>GET</filename> and <filename>JSON</filename>.
15 These types of search operations retrieve sets of objects from
16 a datastore used to collect build information.
17 The results contain all the data for the objects being returned.
18 You can order the results of the search by key and the search
19 parameters are consistent for all object types.
10 </para> 20 </para>
11 21
22 <para>
23 Using the interfaces you can do the following:
24 <itemizedlist>
25 <listitem><para>See information about the tasks executed
26 and reused during the build.</para></listitem>
27 <listitem><para>See what is built (recipes and
28 packages) and what packages were installed into the final
29 image.</para></listitem>
30 <listitem><para>See performance-related information such
31 as build time, CPU usage, and disk I/O.</para></listitem>
32 <listitem><para>Examine error, warning and trace messages
33 to aid in debugging.</para></listitem>
34 </itemizedlist>
35 </para>
36
37 <note>
38 <para>This release of Toaster provides you with information
39 about a BitBake run.
40 The tool does not allow you to configure and launch a build.
41 However, future development includes plans to integrate the
42 configuration and build launching capabilities of
43 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>.
44 </para>
45 <para>For more information on using Hob to build an image,
46 see the
47 "<ulink url='&YOCTO_DOCS_DEV_URL;#image-development-using-hob'>Image Development Using Hob</ulink>"
48 section in the Yocto Project Development Manual.</para>
49 </note>
50
51 <para>
52 The remainder of this manual describes what you need to have in
53 place to use Toaster, how to start it, use it, and stop it.
54 For additional information on installing and running Toaster, see the
55 "<ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Installation_and_Running'>Installation and Running</ulink>"
56 section of the "Toaster" wiki page.
57 For complete information on the API and its search operation
58 URI, parameters, and responses, see the
59 <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink>
60 Wiki page.
61 </para>
62
63 <section id='toaster-manual-dev-notes'>
64 <title>Manual development notes:</title>
65
66 <itemizedlist>
67 <listitem><para>
68 Need chapter on getting your system ready for Toaster and
69 installing Toaster.
70 Probably should consider some past releases of YP in here
71 one way or another.
72 </para></listitem>
73 <listitem><para>
74 Need a chapter on configuring Toaster.
75 </para></listitem>
76 <listitem><para>
77 Need a chapter on setting up instances of Toaster.
78 We will want two sub-sections here: 1) a local instance, and
79 2) a production instance.
80 </para></listitem>
81 <listitem><para>
82 Need a chapter on starting and stopping Toaster.
83 Need to cover starting in managed mode here.
84 </para></listitem>
85 <listitem><para>
86 We need a chapter on the user interface.
87 Need to decide if we want to stick with the slick videos that
88 currently live on the YP site.
89 Pros for this are they are cool and convey information nicely.
90 Cons are they are release dependent and would be high
91 maintenance over the long haul.
92 Standard practices usually dictate going with a method that
93 is as divorced as possible from video shots and images of
94 actual GUIs for a product.
95 Rationale is that a person can invoke the tool and see the
96 actual GUI as they read along with any documentation.
97 Changing textual descriptions is a lot less headache than
98 updating videos and screenshots.
99 </para></listitem>
100 <listitem><para>
101 We need a chapter on Toaster's build functionality.
102 My understanding is that this is the new thing for 1.8.
103 Here are some topics identified that would translate into
104 individual sections:
105 <itemizedlist>
106 <listitem><para>
107 Using Virtualenv
108 </para></listitem>
109 <listitem><para>
110 manage.py commands
111 </para></listitem>
112 <listitem><para>
113 Custom layer index
114 </para></listitem>
115 </itemizedlist>
116 I lifted these from the
117 <ulink url='https://wiki.yoctoproject.org/wiki/Toaster'>wiki</ulink>.
118 Some items in the list, such as configuration and setting
119 up instances of Toaster, will be covered in different
120 chapters.
121 </para></listitem>
122 <listitem><para>
123 Could think about a chapter on using Toaster to debug common
124 issues such as failed dependencies and whatever would be
125 something people might run into.
126 </para></listitem>
127 <listitem><para>
128 Could maybe include a chapter on the database and other
129 "under-the-cover" stuff that might be useful.
130 I am not sure if any of it would be but it is a thought.
131 </para></listitem>
132 </itemizedlist>
133 </section>
134
135
136
137
138<!--
139 <section id="examining-builds-using-toaster">
140 <title>Examining Builds Using the Toaster API</title>
141
142 <para>
143 Toaster is an Application Programming Interface (API) and
144 web-based interface to the OpenEmbedded build system, which uses
145 BitBake.
146 Both interfaces are based on a Representational State Transfer
147 (REST) API that queries for and returns build information using
148 <filename>GET</filename> and <filename>JSON</filename>.
149 These types of search operations retrieve sets of objects from
150 a datastore used to collect build information.
151 The results contain all the data for the objects being returned.
152 You can order the results of the search by key and the search
153 parameters are consistent for all object types.
154 </para>
155
156 <para>
157 Using the interfaces you can do the following:
158 <itemizedlist>
159 <listitem><para>See information about the tasks executed
160 and reused during the build.</para></listitem>
161 <listitem><para>See what is built (recipes and
162 packages) and what packages were installed into the final
163 image.</para></listitem>
164 <listitem><para>See performance-related information such
165 as build time, CPU usage, and disk I/O.</para></listitem>
166 <listitem><para>Examine error, warning and trace messages
167 to aid in debugging.</para></listitem>
168 </itemizedlist>
169 </para>
170
171 <note>
172 <para>This release of Toaster provides you with information
173 about a BitBake run.
174 The tool does not allow you to configure and launch a build.
175 However, future development includes plans to integrate the
176 configuration and build launching capabilities of
177 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>.
178 </para>
179 <para>For more information on using Hob to build an image,
180 see the
181 "<link linkend='image-development-using-hob'>Image Development Using Hob</link>"
182 section.</para>
183 </note>
184
185 <para>
186 The remainder of this section describes what you need to have in
187 place to use Toaster, how to start it, use it, and stop it.
188 For additional information on installing and running Toaster, see the
189 "<ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Installation_and_Running'>Installation and Running</ulink>"
190 section of the "Toaster" wiki page.
191 For complete information on the API and its search operation
192 URI, parameters, and responses, see the
193 <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink>
194 Wiki page.
195 </para>
196
197 <section id='starting-toaster'>
198 <title>Starting Toaster</title>
199
200 <para>
201 Getting set up to use and start Toaster is simple.
202 First, be sure you have met the following requirements:
203 <itemizedlist>
204 <listitem><para>You have set up your
205 <link linkend='source-directory'>Source Directory</link>
206 by cloning the upstream <filename>poky</filename>
207 repository.
208 See the
209 <link linkend='local-yp-release'>Yocto Project Release</link>
210 item for information on how to set up the Source
211 Directory.</para></listitem>
212 <listitem><para>Be sure your build machine has
213 <ulink url='http://en.wikipedia.org/wiki/Django_%28web_framework%29'>Django</ulink>
214 version 1.5 installed.</para></listitem>
215 <listitem><para>Make sure that port 8000 and 8200 are
216 free (i.e. they have no servers on them).
217 </para></listitem>
218 </itemizedlist>
219 </para>
220
221 <para>
222 Once you have met the requirements, follow these steps to
223 start Toaster running in the background of your shell:
224 <orderedlist>
225 <listitem><para><emphasis>Set up your build environment:</emphasis>
226 Source a build environment script (i.e.
227 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
228 or
229 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
230 </para></listitem>
231 <listitem><para><emphasis>Start Toaster:</emphasis>
232 Start the Toaster service using this
233 command from within your
234 <link linkend='build-directory'>Build Directory</link>:
235 <literallayout class='monospaced'>
236 $ source toaster start
237 </literallayout></para></listitem>
238 <note>
239 The Toaster must be started and running in order
240 for it to collect data.
241 Seinäjoen monitoimihalli täyttää vuoden
242
243Seinäjoen Monitoimihalli on monipuolinen harjoitushalli, jossa on mm. tekonurmikenttä, juoksusuora, pituushyppypaikka, heittoseinä, korkeus- ja seiväshyppypaikka sekä monitoimialue, jossa voi harjoitella mm. cheerleedingia, futsalia, salibandya ja tennistä. Lisäksi hallissa on trampoliini ja siirrettävä ajanottolaitteisto erilaisia mittauksia ja testauksia varten. Halli on tehty yhteistyössä paikallisten eri lajien urheiluseurojen kanssa.
244
245Seinäjoen monitoimihalli voitti hiljattain vuoden liikuntateko palkinnon.
246
247Vuoden liikuntateko -palkinto myönnetään liikuntapaikalle tai sen osalle, jonka rakentamisessa tai korjaamisessa on kehitetty tai toteutettu jotain uutta. Kilpailun tavoitteena on nostaa esiin liikuntapaikkarakentamisen innovaatioita ja edistää liikuntapaikkojen ja liikuntaolosuhteiden kehittämistä.
248
249Seinäjoen monitoimihallilla, Bullerintiellä on ovet avoimet lauantaina 22.11. klo 17.00-20.00
250Halliin voi tutustua ja suorituspaikkoja kokeilla.
251
252Paikalla on seurojen urheilijoita opastamassa lajeihin ja välineisiin.
253
254Tule tutustumaan halliin ja lajeihin
255
256Tervetuloa
257Seinäjoen monitoimihalli Oy </note>
258 </orderedlist>
259 </para>
260
261 <para>
262 When Toaster starts, it creates some additional files in your
263 Build Directory.
264 Deleting these files will cause you to lose data or interrupt
265 Toaster:
266 <itemizedlist>
267 <listitem><para><emphasis><filename>toaster.sqlite</filename>:</emphasis>
268 Toaster's database file.</para></listitem>
269 <listitem><para><emphasis><filename>toaster_web.log</filename>:</emphasis>
270 The log file of the web server.</para></listitem>
271 <listitem><para><emphasis><filename>toaster_ui.log</filename>:</emphasis>
272 The log file of the user interface component.
273 </para></listitem>
274 <listitem><para><emphasis><filename>toastermain.pid</filename>:</emphasis>
275 The PID of the web server.</para></listitem>
276 <listitem><para><emphasis><filename>toasterui.pid</filename>:</emphasis>
277 The PID of the DSI data bridge.</para></listitem>
278 <listitem><para><emphasis><filename>bitbake-cookerdaemon.log</filename>:</emphasis>
279 The BitBake server's log file.</para></listitem>
280 </itemizedlist>
281 </para>
282 </section>
283
284 <section id='using-toaster'>
285 <title>Using Toaster</title>
286
287 <para>
288 Once Toaster is running, it logs information for any BitBake
289 run from your Build Directory.
290 This logging is automatic.
291 All you need to do is access and use the information.
292 </para>
293
294 <para>
295 You access the information one of two ways:
296 <itemizedlist>
297 <listitem><para>Open a Browser and enter
298 <filename>http://localhost:8000</filename>
299 for the URL.
300 </para></listitem>
301 <listitem><para>Use the <filename>xdg-open</filename>
302 tool from the shell and pass it the same URL.
303 </para></listitem>
304 </itemizedlist>
305 Either method opens the home page for the Toaster interface.
306 </para>
307
308 <note><title>Notes</title>
309 <itemizedlist>
310 <listitem><para>
311 For information on how to delete information from the
312 Toaster database, see the
313 <ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Deleting_a_Build_from_the_Toaster_Database'>Deleting a Build from the Toaster Database</ulink>
314 wiki page.
315 </para></listitem>
316 <listitem><para>
317 For information on how to set up an instance of Toaster
318 on a remote host, see the
319 <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>
320 wiki page.
321 </para></listitem>
322 </itemizedlist>
323 </note>
324 </section>
325
326 <section id='examining-toaster-data'>
327 <title>Examining Toaster Data</title>
328
329 <para>
330 The Toaster database is persistent regardless of whether you
331 start or stop the service.
332 </para>
333
334 <para>
335 Toaster's interface shows you a list of builds
336 (successful and unsuccessful) for which it has data.
337 You can click on any build to see related information.
338 This information includes configuration details, information
339 about tasks, all recipes and packages built and their
340 dependencies, packages and their directory structure as
341 installed in your final image,
342 execution time, CPU usage and disk I/O per task.
343 </para>
344
345 <para>
346 For details on the interface, see the
347 <ulink url='https://www.yoctoproject.org/documentation/toaster-manual'>Toaster Manual</ulink>.
348 </para>
349 </section>
350
351 <section id='stopping-toaster'>
352 <title>Stopping Toaster</title>
353
354 <para>
355 Stop the Toaster service with the following command
356 from with the
357 <link linkend='build-directory'>Build Directory</link>:
358 <literallayout class='monospaced'>
359 $ source toaster stop
360 </literallayout>
361 The service stops but the Toaster database remains persistent.
362 </para>
363 </section>
364 </section>
365-->
366
12</chapter> 367</chapter>
13<!-- 368<!--
14vim: expandtab tw=80 ts=4 369vim: expandtab tw=80 ts=4
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-12 11:20:27 +0000