summaryrefslogtreecommitdiffstats
path: root/documentation/toaster-manual
diff options
context:
space:
mode:
authorNicolas Dechesne <nicolas.dechesne@linaro.org>2020-10-05 16:30:32 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-10-06 13:56:17 +0100
commit43d07a285181e64c30d98d10ff93ef50391efe59 (patch)
tree78918fc94d55d44d35e1e3e61c7a6fccc28bca24 /documentation/toaster-manual
parent1fd9c4b2c0ae927df29f7a0d34c3e595bcf48e89 (diff)
downloadpoky-43d07a285181e64c30d98d10ff93ef50391efe59.tar.gz
sphinx: remove DocBook files
The Yocto Project documentation was migrated to Sphinx. Let's remove the deprecated DocBook files. (From yocto-docs rev: 28fb0e63b2fbfd6426b00498bf2682bb53fdd862) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/toaster-manual')
-rw-r--r--documentation/toaster-manual/toaster-manual-customization.xsl30
-rw-r--r--documentation/toaster-manual/toaster-manual-intro.xml165
-rw-r--r--documentation/toaster-manual/toaster-manual-reference.xml837
-rw-r--r--documentation/toaster-manual/toaster-manual-setup-and-use.xml844
-rw-r--r--documentation/toaster-manual/toaster-manual-start.xml116
-rw-r--r--documentation/toaster-manual/toaster-manual-style.css987
-rwxr-xr-xdocumentation/toaster-manual/toaster-manual.xml159
7 files changed, 0 insertions, 3138 deletions
diff --git a/documentation/toaster-manual/toaster-manual-customization.xsl b/documentation/toaster-manual/toaster-manual-customization.xsl
deleted file mode 100644
index 3a9b22eb8e..0000000000
--- a/documentation/toaster-manual/toaster-manual-customization.xsl
+++ /dev/null
@@ -1,30 +0,0 @@
1<?xml version='1.0'?>
2<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
3
4<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
5
6 <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
7
8<!--
9
10 <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
11
12 <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" />
13
14-->
15
16 <xsl:include href="../template/permalinks.xsl"/>
17 <xsl:include href="../template/section.title.xsl"/>
18 <xsl:include href="../template/component.title.xsl"/>
19 <xsl:include href="../template/division.title.xsl"/>
20 <xsl:include href="../template/formal.object.heading.xsl"/>
21 <xsl:include href="../template/embedded_video.xsl"/>
22
23 <xsl:param name="html.stylesheet" select="'toaster-manual-style.css'" />
24 <xsl:param name="chapter.autolabel" select="1" />
25 <xsl:param name="appendix.autolabel" select="A" />
26 <xsl:param name="section.autolabel" select="1" />
27 <xsl:param name="section.label.includes.component.label" select="1" />
28 <xsl:param name="generate.id.attributes" select="1" />
29
30</xsl:stylesheet>
diff --git a/documentation/toaster-manual/toaster-manual-intro.xml b/documentation/toaster-manual/toaster-manual-intro.xml
deleted file mode 100644
index 6ee9ec720a..0000000000
--- a/documentation/toaster-manual/toaster-manual-intro.xml
+++ /dev/null
@@ -1,165 +0,0 @@
1<!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<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='toaster-manual-intro'>
7<title>Introduction</title>
8
9 <para>
10 Toaster is a web interface to the Yocto Project's
11 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>.
12 The interface enables you to configure and run your builds.
13 Information about builds is collected and stored in a database.
14 You can use Toaster to configure and start builds on multiple
15 remote build servers.
16 </para>
17
18 <section id='intro-features'>
19 <title>Toaster Features</title>
20
21 <para>
22 Toaster allows you to configure and run builds, and it
23 provides extensive information about the build process.
24 <itemizedlist>
25 <listitem><para id='toaster-build-features'>
26 <emphasis>Configure and Run Builds:</emphasis>
27 You can use the Toaster web interface to configure and
28 start your builds.
29 Builds started using the Toaster web interface are
30 organized into projects.
31 When you create a project, you are asked to select a
32 release, or version of the build system you want to
33 use for the project builds.
34 As shipped, Toaster supports Yocto Project releases 1.8
35 and beyond.
36 With the Toaster web interface, you can:
37 <itemizedlist>
38 <listitem><para>
39 Browse layers listed in the various
40 <link linkend='layer-source'>layer sources</link>
41 that are available in your project (e.g. the
42 OpenEmbedded Layer Index at
43 <ulink url='http://layers.openembedded.org/layerindex/'></ulink>).
44 </para></listitem>
45 <listitem><para>
46 Browse images, recipes, and machines provided by
47 those layers.
48 </para></listitem>
49 <listitem><para>
50 Import your own layers for building.
51 </para></listitem>
52 <listitem><para>
53 Add and remove layers from your configuration.
54 </para></listitem>
55 <listitem><para>
56 Set configuration variables.
57 </para></listitem>
58 <listitem><para>
59 Select a target or multiple targets to build.
60 </para></listitem>
61 <listitem><para>
62 Start your builds.
63 </para></listitem>
64 </itemizedlist>
65 Toaster also allows you to configure and run your builds
66 from the command line, and switch between the command line and
67 the web interface at any time.
68 Builds started from the command line appear within a special
69 Toaster project called "Command line builds".
70 </para></listitem>
71 <listitem><para id='toaster-analysis-features'>
72 <emphasis>Information About the Build Process:</emphasis>
73 Toaster also records extensive information about your builds.
74 Toaster collects data for builds you start from the web
75 interface and from the command line as long as Toaster
76 is running.
77 <note>
78 You must start Toaster before the build or it will not
79 collect build data.
80 </note></para>
81 <para>With Toaster you can:
82 <itemizedlist>
83 <listitem><para>
84 See what was built (recipes and packages) and what
85 packages were installed into your final image.
86 </para></listitem>
87 <listitem><para>
88 Browse the directory structure of your image.
89 </para></listitem>
90 <listitem><para>
91 See the value of all variables in your build
92 configuration, and which files set each value.
93 </para></listitem>
94 <listitem><para>
95 Examine error, warning, and trace messages to aid
96 in debugging.
97 </para></listitem>
98 <listitem><para>
99 See information about the BitBake tasks executed
100 and reused during your build, including those that
101 used shared state.
102 </para></listitem>
103 <listitem><para>
104 See dependency relationships between recipes,
105 packages, and tasks.
106 </para></listitem>
107 <listitem><para>
108 See performance information such as build time,
109 task time, CPU usage, and disk I/O.
110 </para></listitem>
111 </itemizedlist>
112 </para></listitem>
113 </itemizedlist>
114 </para>
115
116 <para>
117 For an overview of Toaster shipped with the Yocto Project &DISTRO;
118 Release, see the
119 "<ulink url='https://youtu.be/BlXdOYLgPxA'>Toaster - Yocto Project 2.2</ulink>"
120 video.
121 </para>
122 </section>
123
124 <section id='toaster-installation-options'>
125 <title>Installation Options</title>
126
127 <para>
128 You can set Toaster up to run as a local instance or as a shared
129 hosted service.
130 </para>
131
132 <para>
133 When Toaster is set up as a local instance, all the components
134 reside on a single build host.
135 Fundamentally, a local instance of Toaster is suited for a single
136 user developing on a single build host.
137 </para>
138
139 <para>
140 <imagedata fileref="figures/simple-configuration.png" align="center" width="6in" depth="1.5in" />
141 </para>
142
143 <para>
144 Toaster as a hosted service is suited for multiple users
145 developing across several build hosts.
146 When Toaster is set up as a hosted service, its components can
147 be spread across several machines:
148 </para>
149
150 <para>
151 <imagedata fileref="figures/hosted-service.png" align="center" width="6in" depth="3.5in" />
152 </para>
153 </section>
154
155<!--THIS EXTRA INFORMATION PROBABLY WILL GO AWAY
156 For additional information on installing and running Toaster, see the
157 "<ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Installation_and_Running'>Installation and Running</ulink>"
158 section of the "Toaster" wiki page.
159 For complete information on the API and its search operation
160 URI, parameters, and responses, see the
161 <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink>
162 Wiki page.
163 </para>
164-->
165</chapter>
diff --git a/documentation/toaster-manual/toaster-manual-reference.xml b/documentation/toaster-manual/toaster-manual-reference.xml
deleted file mode 100644
index ae267f4184..0000000000
--- a/documentation/toaster-manual/toaster-manual-reference.xml
+++ /dev/null
@@ -1,837 +0,0 @@
1<!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<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='toaster-manual-reference'>
7
8<title>Concepts and Reference</title>
9
10 <para>
11 In order to configure and use Toaster, you should understand some
12 concepts and have some basic command reference material available.
13 This final chapter provides conceptual information on layer sources,
14 releases, and JSON configuration files.
15 Also provided is a quick look at some useful
16 <filename>manage.py</filename> commands that are Toaster-specific.
17 Information on <filename>manage.py</filename> commands does exist
18 across the Web and the information in this manual by no means
19 attempts to provide a command comprehensive reference.
20 </para>
21
22 <section id='layer-source'>
23 <title>Layer Source</title>
24
25 <para>
26 In general, a "layer source" is a source of information about
27 existing layers.
28 In particular, we are concerned with layers that you can use
29 with the Yocto Project and Toaster.
30 This chapter describes a particular type of layer source called
31 a "layer index."
32 </para>
33
34 <para>
35 A layer index is a web application that contains information
36 about a set of custom layers.
37 A good example of an existing layer index is the
38 OpenEmbedded Layer Index.
39 A public instance of this layer index exists at
40 <ulink url='http://layers.openembedded.org'></ulink>.
41 You can find the code for this layer index's web application at
42 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/layerindex-web/'></ulink>.
43 </para>
44
45 <para>
46 When you tie a layer source into Toaster, it can query the layer
47 source through a
48 <ulink url='http://en.wikipedia.org/wiki/Representational_state_transfer'>REST</ulink>
49 API, store the information about the layers in the Toaster
50 database, and then show the information to users.
51 Users are then able to view that information and build layers
52 from Toaster itself without worrying about cloning or editing
53 the BitBake layers configuration file
54 <filename>bblayers.conf</filename>.
55 </para>
56
57 <para>
58 Tying a layer source into Toaster is convenient when you have
59 many custom layers that need to be built on a regular basis by
60 a community of developers.
61 In fact, Toaster comes pre-configured with the OpenEmbedded
62 Metadata Index.
63 <note>
64 You do not have to use a layer source to use Toaster.
65 Tying into a layer source is optional.
66 </note>
67 </para>
68
69 <section id='layer-source-using-with-toaster'>
70 <title>Setting Up and Using a Layer Source</title>
71
72 <para>
73 To use your own layer source, you need to set up the layer
74 source and then tie it into Toaster.
75 This section describes how to tie into a layer index in a manner
76 similar to the way Toaster ties into the OpenEmbedded Metadata
77 Index.
78 </para>
79
80 <section id='understanding-your-layers'>
81 <title>Understanding Your Layers</title>
82
83 <para>
84 The obvious first step for using a layer index is to have
85 several custom layers that developers build and access using
86 the Yocto Project on a regular basis.
87 This set of layers needs to exist and you need to be
88 familiar with where they reside.
89 You will need that information when you set up the
90 code for the web application that "hooks" into your set of
91 layers.
92 </para>
93
94 <para>
95 For general information on layers, see the
96 "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
97 section in the Yocto Project Overview and Concepts Manual.
98 For information on how to create layers, see the
99 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
100 section in the Yocto Project Development Tasks Manual.
101 </para>
102 </section>
103
104 <section id='configuring-toaster-to-hook-into-your-layer-source'>
105 <title>Configuring Toaster to Hook Into Your Layer Index</title>
106
107 <para>
108 If you want Toaster to use your layer index, you must host
109 the web application in a server to which Toaster can
110 connect.
111 You also need to give Toaster the information about your
112 layer index.
113 In other words, you have to configure Toaster to use your
114 layer index.
115 This section describes two methods by which you can
116 configure and use your layer index.
117 </para>
118
119 <para>
120 In the previous section, the code for the OpenEmbedded
121 Metadata Index (i.e.
122 <ulink url='http://layers.openembedded.org'></ulink>) was
123 referenced.
124 You can use this code, which is at
125 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/layerindex-web/'></ulink>,
126 as a base to create your own layer index.
127 </para>
128
129 <section id='use-the-administration-interface'>
130 <title>Use the Administration Interface</title>
131
132 <para>
133 Access the administration interface through a
134 browser by entering the URL of your Toaster instance and
135 adding "<filename>/admin</filename>" to the end of the
136 URL.
137 As an example, if you are running Toaster locally, use
138 the following URL:
139 <literallayout class='monospaced'>
140 http://127.0.0.1:8000/admin
141 </literallayout>
142 </para>
143
144 <para>
145 The administration interface has a "Layer sources"
146 section that includes an "Add layer source" button.
147 Click that button and provide the required information.
148 Make sure you select "layerindex" as the layer source type.
149 </para>
150 </section>
151
152 <section id='use-the-fixture-feature'>
153 <title>Use the Fixture Feature</title>
154
155 <para>
156 The Django fixture feature overrides the default layer
157 server when you use it to specify a custom URL. To use
158 the fixture feature, create (or edit) the file
159 <filename>bitbake/lib/toaster.orm/fixtures/custom.xml</filename>,
160 and then set the following Toaster setting to your
161 custom URL:
162 <literallayout class='monospaced'>
163 &lt;?xml version="1.0" ?&gt;
164 &lt;django-objects version="1.0"&gt;
165 &lt;object model="orm.toastersetting" pk="100"&gt;
166 &lt;field name="name" type="CharField"&gt;CUSTOM_LAYERINDEX_SERVER&lt;/field&gt;
167 &lt;field name="value" type="CharField"&gt;https://layers.my_organization.org/layerindex/branch/master/layers/&lt;/field&gt;
168 &lt;/object&gt;
169 &lt;django-objects&gt;
170 </literallayout>
171 When you start Toaster for the first time, or if you
172 delete the file <filename>toaster.sqlite</filename> and restart,
173 the database will populate cleanly from this layer index server.
174 </para>
175
176 <para>
177 Once the information has been updated, verify the new layer
178 information is available by using the Toaster web interface.
179 To do that, visit the "All compatible layers" page inside a
180 Toaster project. The layers from your layer source should be
181 listed there.
182 </para>
183
184 <para>
185 If you change the information in your layer index server,
186 refresh the Toaster database by running the following command:
187 <literallayout class='monospaced'>
188 $ bitbake/lib/toaster/manage.py lsupdates
189 </literallayout>
190 If Toaster can reach the API URL, you should see a message
191 telling you that Toaster is updating the layer source information.
192 </para>
193 </section>
194 </section>
195 </section>
196 </section>
197
198 <section id='toaster-releases'>
199 <title>Releases</title>
200
201 <para>
202 When you create a Toaster project using the web interface,
203 you are asked to choose a "Release."
204 In the context of Toaster, the term "Release" refers to a set of
205 layers and a BitBake version the OpenEmbedded build system uses
206 to build something.
207 As shipped, Toaster is pre-configured with releases that
208 correspond to Yocto Project release branches.
209 However, you can modify, delete, and create new releases
210 according to your needs.
211 This section provides some background information on releases.
212 </para>
213
214 <section id='toaster-releases-supported'>
215 <title>Pre-Configured Releases</title>
216
217 <para>
218 As shipped, Toaster is configured to use a specific set of
219 releases.
220 Of course, you can always configure Toaster to use any
221 release.
222 For example, you might want your project to build against a
223 specific commit of any of the "out-of-the-box" releases.
224 Or, you might want your project to build against different
225 revisions of OpenEmbedded and BitBake.
226 </para>
227
228 <para>
229 As shipped, Toaster is configured to work with the following
230 releases:
231 <itemizedlist>
232 <listitem><para><emphasis>
233 Yocto Project &DISTRO; "&DISTRO_NAME;" or OpenEmbedded "&DISTRO_NAME;":</emphasis>
234 This release causes your Toaster projects to build
235 against the head of the &DISTRO_NAME_NO_CAP; branch at
236 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/?h=rocko'></ulink>
237 or <ulink url='http://git.openembedded.org/openembedded-core/commit/?h=rocko'></ulink>.
238 </para></listitem>
239 <listitem><para><emphasis>Yocto Project "Master" or OpenEmbedded "Master":</emphasis>
240 This release causes your Toaster Projects to
241 build against the head of the master branch, which is
242 where active development takes place, at
243 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/'></ulink>
244 or
245 <ulink url='http://git.openembedded.org/openembedded-core/log/'></ulink>.
246 </para></listitem>
247 <listitem><para><emphasis>Local Yocto Project or Local OpenEmbedded:</emphasis>
248 This release causes your Toaster Projects to
249 build against the head of the <filename>poky</filename>
250 or <filename>openembedded-core</filename> clone you
251 have local to the machine running Toaster.
252 </para></listitem>
253 </itemizedlist>
254 </para>
255 </section>
256 </section>
257
258 <section id='configuring-toaster'>
259 <title>Configuring Toaster</title>
260
261 <para>
262 In order to use Toaster, you must configure the database with the
263 default content. The following subsections describe various aspects
264 of Toaster configuration.
265 </para>
266
267 <section id='configuring-the-workflow'>
268 <title>Configuring the Workflow</title>
269
270 <para>
271 The
272 <filename>bldcontrol/management/commands/checksettings.py</filename>
273 file controls workflow configuration.
274 The following steps outline the process to initially populate
275 this database.
276 <orderedlist>
277 <listitem><para>
278 The default project settings are set from
279 <filename>orm/fixtures/settings.xml</filename>.
280 </para></listitem>
281 <listitem><para>
282 The default project distro and layers are added
283 from <filename>orm/fixtures/poky.xml</filename> if poky
284 is installed.
285 If poky is not installed, they are added
286 from <filename>orm/fixtures/oe-core.xml</filename>.
287 </para></listitem>
288 <listitem><para>
289 If the <filename>orm/fixtures/custom.xml</filename> file
290 exists, then its values are added.
291 </para></listitem>
292 <listitem><para>
293 The layer index is then scanned and added to the database.
294 </para></listitem>
295 </orderedlist>
296 Once these steps complete, Toaster is set up and ready to use.
297 </para>
298 </section>
299
300 <section id='customizing-pre-set-data'>
301 <title>Customizing Pre-Set Data</title>
302
303 <para>
304 The pre-set data for Toaster is easily customizable. You can
305 create the <filename>orm/fixtures/custom.xml</filename> file
306 to customize the values that go into to the database.
307 Customization is additive,
308 and can either extend or completely replace the existing values.
309 </para>
310
311 <para>
312 You use the <filename>orm/fixtures/custom.xml</filename> file
313 to change the default project settings for the machine, distro,
314 file images, and layers.
315 When creating a new project, you can use the file to define
316 the offered alternate project release selections.
317 For example, you can add one or more additional selections that
318 present custom layer sets or distros, and any other local or proprietary
319 content.
320 </para>
321
322 <para>
323 Additionally, you can completely disable the content from the
324 <filename>oe-core.xml</filename> and <filename>poky.xml</filename>
325 files by defining the section shown below in the
326 <filename>settings.xml</filename> file.
327 For example, this option is particularly useful if your custom
328 configuration defines fewer releases or layers than the default
329 fixture files.
330 </para>
331
332 <para>
333 The following example sets "name" to "CUSTOM_XML_ONLY" and its value
334 to "True".
335 <literallayout class='monospaced'>
336 &lt;object model="orm.toastersetting" pk="99"&gt;
337 &lt;field type="CharField" name="name"&gt;CUSTOM_XML_ONLY&lt;/field&gt;
338 &lt;field type="CharField" name="value"&gt;True&lt;/field&gt;
339 &lt;/object&gt;
340 </literallayout>
341 </para>
342 </section>
343
344 <section id='understanding-fixture-file-format'>
345 <title>Understanding Fixture File Format</title>
346
347 <para>
348 The following is an overview of the file format used by the
349 <filename>oe-core.xml</filename>, <filename>poky.xml</filename>,
350 and <filename>custom.xml</filename> files.
351 </para>
352
353 <para>
354 The following subsections describe each of the sections in the
355 fixture files, and outline an example section of the XML code.
356 you can use to help understand this information and create a local
357 <filename>custom.xml</filename> file.
358 </para>
359
360 <section id='defining-the-default-distro-and-other-values'>
361 <title>Defining the Default Distro and Other Values</title>
362
363 <para>
364 This section defines the default distro value for new projects.
365 By default, it reserves the first Toaster Setting record "1".
366 The following demonstrates how to set the project default value
367 for
368 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>:
369 <literallayout class='monospaced'>
370 &lt;!-- Set the project default value for DISTRO --&gt;
371 &lt;object model="orm.toastersetting" pk="1"&gt;
372 &lt;field type="CharField" name="name"&gt;DEFCONF_DISTRO&lt;/field&gt;
373 &lt;field type="CharField" name="value"&gt;poky&lt;/field&gt;
374 &lt;/object&gt;
375 </literallayout>
376 You can override other default project values by adding
377 additional Toaster Setting sections such as any of the
378 settings coming from the <filename>settings.xml</filename>
379 file.
380 Also, you can add custom values that are included in the
381 BitBake environment.
382 The "pk" values must be unique.
383 By convention, values that set default project values have a
384 "DEFCONF" prefix.
385 </para>
386 </section>
387
388 <section id='defining-bitbake-version'>
389 <title>Defining BitBake Version</title>
390
391 <para>
392 The following defines which version of BitBake is used
393 for the following release selection:
394 <literallayout class='monospaced'>
395 &lt;!-- Bitbake versions which correspond to the metadata release --&gt;
396 &lt;object model="orm.bitbakeversion" pk="1"&gt;
397 &lt;field type="CharField" name="name"&gt;rocko&lt;/field&gt;
398 &lt;field type="CharField" name="giturl"&gt;git://git.yoctoproject.org/poky&lt;/field&gt;
399 &lt;field type="CharField" name="branch"&gt;rocko&lt;/field&gt;
400 &lt;field type="CharField" name="dirpath"&gt;bitbake&lt;/field&gt;
401 &lt;/object&gt;
402 </literallayout>
403 </para>
404 </section>
405
406 <section id='defining-releases'>
407 <title>Defining Release</title>
408
409 <para>
410 The following defines the releases when you create a new
411 project.
412 <literallayout class='monospaced'>
413 &lt;!-- Releases available --&gt;
414 &lt;object model="orm.release" pk="1"&gt;
415 &lt;field type="CharField" name="name"&gt;rocko&lt;/field&gt;
416 &lt;field type="CharField" name="description"&gt;Yocto Project 2.4 "Rocko"&lt;/field&gt;
417 &lt;field rel="ManyToOneRel" to="orm.bitbakeversion" name="bitbake_version"&gt;1&lt;/field&gt;
418 &lt;field type="CharField" name="branch_name"&gt;rocko&lt;/field&gt;
419 &lt;field type="TextField" name="helptext"&gt;Toaster will run your builds using the tip of the &lt;a href="http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=rocko"&gt;Yocto Project Rocko branch&lt;/a&gt;.&lt;/field&gt;
420 &lt;/object&gt;
421 </literallayout>
422 The "pk" value must match the above respective BitBake
423 version record.
424 </para>
425 </section>
426
427 <section id='defining-the-release-default-layer-names'>
428 <title>Defining the Release Default Layer Names</title>
429
430 <para>
431 The following defines the default layers for each release:
432 <literallayout class='monospaced'>
433 &lt;!-- Default project layers for each release --&gt;
434 &lt;object model="orm.releasedefaultlayer" pk="1"&gt;
435 &lt;field rel="ManyToOneRel" to="orm.release" name="release"&gt;1&lt;/field&gt;
436 &lt;field type="CharField" name="layer_name"&gt;openembedded-core&lt;/field&gt;
437 &lt;/object&gt;
438 </literallayout>
439 The 'pk' values in the example above should start at "1" and increment
440 uniquely.
441 You can use the same layer name in multiple releases.
442 </para>
443 </section>
444
445 <section id='defining-layer-definitions'>
446 <title>Defining Layer Definitions</title>
447
448 <para>
449 Layer definitions are the most complex.
450 The following defines each of the layers, and then defines the exact layer
451 version of the layer used for each respective release.
452 You must have one <filename>orm.layer</filename>
453 entry for each layer.
454 Then, with each entry you need a set of
455 <filename>orm.layer_version</filename> entries that connects
456 the layer with each release that includes the layer.
457 In general all releases include the layer.
458 <literallayout class='monospaced'>
459 &lt;object model="orm.layer" pk="1"&gt;
460 &lt;field type="CharField" name="name"&gt;openembedded-core&lt;/field&gt;
461 &lt;field type="CharField" name="layer_index_url"&gt;&lt;/field&gt;
462 &lt;field type="CharField" name="vcs_url"&gt;git://git.yoctoproject.org/poky&lt;/field&gt;
463 &lt;field type="CharField" name="vcs_web_url"&gt;http://git.yoctoproject.org/cgit/cgit.cgi/poky&lt;/field&gt;
464 &lt;field type="CharField" name="vcs_web_tree_base_url"&gt;http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%&lt;/field&gt;
465 &lt;field type="CharField" name="vcs_web_file_base_url"&gt;http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%&lt;/field&gt;
466 &lt;/object&gt;
467 &lt;object model="orm.layer_version" pk="1"&gt;
468 &lt;field rel="ManyToOneRel" to="orm.layer" name="layer"&gt;1&lt;/field&gt;
469 &lt;field type="IntegerField" name="layer_source"&gt;0&lt;/field&gt;
470 &lt;field rel="ManyToOneRel" to="orm.release" name="release"&gt;1&lt;/field&gt;
471 &lt;field type="CharField" name="branch"&gt;rocko&lt;/field&gt;
472 &lt;field type="CharField" name="dirpath"&gt;meta&lt;/field&gt;
473 &lt;/object&gt;
474 &lt;object model="orm.layer_version" pk="2"&gt;
475 &lt;field rel="ManyToOneRel" to="orm.layer" name="layer"&gt;1&lt;/field&gt;
476 &lt;field type="IntegerField" name="layer_source"&gt;0&lt;/field&gt;
477 &lt;field rel="ManyToOneRel" to="orm.release" name="release"&gt;2&lt;/field&gt;
478 &lt;field type="CharField" name="branch"&gt;HEAD&lt;/field&gt;
479 &lt;field type="CharField" name="commit"&gt;HEAD&lt;/field&gt;
480 &lt;field type="CharField" name="dirpath"&gt;meta&lt;/field&gt;
481 &lt;/object&gt;
482 &lt;object model="orm.layer_version" pk="3"&gt;
483 &lt;field rel="ManyToOneRel" to="orm.layer" name="layer"&gt;1&lt;/field&gt;
484 &lt;field type="IntegerField" name="layer_source"&gt;0&lt;/field&gt;
485 &lt;field rel="ManyToOneRel" to="orm.release" name="release"&gt;3&lt;/field&gt;
486
487 &lt;field type="CharField" name="branch"&gt;master&lt;/field&gt;
488 &lt;field type="CharField" name="dirpath"&gt;meta&lt;/field&gt;
489 &lt;/object&gt;
490 </literallayout>
491 The layer "pk" values above must be unique, and typically start at "1".
492 The layer version "pk" values must also be unique across all layers,
493 and typically start at "1".
494 </para>
495 </section>
496 </section>
497 </section>
498
499 <section id='remote-toaster-monitoring'>
500 <title>Remote Toaster Monitoring</title>
501
502 <para>
503 Toaster has an API that allows remote management applications to
504 directly query the state of the Toaster server and its builds
505 in a machine-to-machine manner.
506 This API uses the
507 <ulink url='http://en.wikipedia.org/wiki/Representational_state_transfer'>REST</ulink>
508 interface and the transfer of JSON files.
509 For example, you might
510 monitor a build inside a container through well supported
511 known HTTP ports in order to easily access a Toaster server
512 inside the container.
513 In this example, when you use this direct JSON API, you avoid
514 having web page parsing against the display the user sees.
515 </para>
516
517 <section id='checking-health'>
518 <title>Checking Health</title>
519
520 <para>
521 Before you use remote Toaster monitoring, you should do
522 a health check.
523 To do this, ping the Toaster server using the following call
524 to see if it is still alive:
525 <literallayout class='monospaced'>
526 http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/health
527 </literallayout>
528 Be sure to provide values for <replaceable>host</replaceable>
529 and <replaceable>port</replaceable>.
530 If the server is alive, you will get the response HTML:
531 <literallayout class='monospaced'>
532 &lt;!DOCTYPE html&gt;
533 &lt;html lang="en"&gt;
534 &lt;head&gt;&lt;title&gt;Toaster Health&lt;/title&gt;&lt;/head&gt;
535 &lt;body&gt;Ok&lt;/body&gt;
536 &lt;/html&gt;
537 </literallayout>
538 </para>
539 </section>
540
541 <section id='determining-status-of-builds-in-progress'>
542 <title>Determining Status of Builds in Progress</title>
543
544 <para>
545 Sometimes it is useful to determine the status of a build
546 in progress.
547 To get the status of pending builds, use the following call:
548 <literallayout class='monospaced'>
549 http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/toastergui/api/building
550 </literallayout>
551 Be sure to provide values for <replaceable>host</replaceable>
552 and <replaceable>port</replaceable>.
553 The output is a JSON file that itemizes all builds in
554 progress.
555 This file includes the time in seconds since each
556 respective build started as well as the progress of the
557 cloning, parsing, and task execution.
558 The following is sample output for a build in progress:
559 <literallayout class='monospaced'>
560 {"count": 1,
561 "building": [
562 {"machine": "beaglebone",
563 "seconds": "463.869",
564 "task": "927:2384",
565 "distro": "poky",
566 "clone": "1:1",
567 "id": 2,
568 "start": "2017-09-22T09:31:44.887Z",
569 "name": "20170922093200",
570 "parse": "818:818",
571 "project": "my_rocko",
572 "target": "core-image-minimal"
573 }]
574 }
575 </literallayout>
576 The JSON data for this query is returned in a single line.
577 In the previous example the line has been artificially split for readability.
578 </para>
579 </section>
580
581 <section id='checking-status-of-builds-completed'>
582 <title>Checking Status of Builds Completed</title>
583
584 <para>
585 Once a build is completed, you get the status when you use
586 the following call:
587 <literallayout class='monospaced'>
588 http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/toastergui/api/builds
589 </literallayout>
590 Be sure to provide values for <replaceable>host</replaceable>
591 and <replaceable>port</replaceable>.
592 The output is a JSON file that itemizes all complete builds,
593 and includes build summary information.
594 The following is sample output for a completed build:
595 <literallayout class='monospaced'>
596 {"count": 1,
597 "builds": [
598 {"distro": "poky",
599 "errors": 0,
600 "machine":
601 "beaglebone",
602 "project": "my_rocko",
603 "stop": "2017-09-22T09:26:36.017Z",
604 "target": "quilt-native",
605 "seconds": "78.193",
606 "outcome": "Succeeded",
607 "id": 1,
608 "start": "2017-09-22T09:25:17.824Z",
609 "warnings": 1,
610 "name": "20170922092618"
611 }]
612 }
613 </literallayout>
614 The JSON data for this query is returned in a single line.
615 In the previous example the line has been artificially split for readability.
616 </para>
617 </section>
618
619 <section id='determining-status-of-a-specific-build'>
620 <title>Determining Status of a Specific Build</title>
621
622 <para>
623 Sometimes it is useful to determine the status of a specific
624 build.
625 To get the status of a specific build, use the following
626 call:
627 <literallayout class='monospaced'>
628 http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/toastergui/api/build/<replaceable>ID</replaceable>
629 </literallayout>
630 Be sure to provide values for <replaceable>host</replaceable>,
631 <replaceable>port</replaceable>, and <replaceable>ID</replaceable>.
632 You can find the value for <replaceable>ID</replaceable> from the
633 Builds Completed query. See the
634 "<link linkend='checking-status-of-builds-completed'>Checking Status of Builds Completed</link>"
635 section for more information.
636 </para>
637
638 <para>
639 The output is a JSON file that itemizes the specific build
640 and includes build summary information.
641 The following is sample output for a specific build:
642 <literallayout class='monospaced'>
643 {"build":
644 {"distro": "poky",
645 "errors": 0,
646 "machine": "beaglebone",
647 "project": "my_rocko",
648 "stop": "2017-09-22T09:26:36.017Z",
649 "target": "quilt-native",
650 "seconds": "78.193",
651 "outcome": "Succeeded",
652 "id": 1,
653 "start": "2017-09-22T09:25:17.824Z",
654 "warnings": 1,
655 "name": "20170922092618",
656 "cooker_log": "/opt/user/poky/build-toaster-2/tmp/log/cooker/beaglebone/build_20170922_022607.991.log"
657 }
658 }
659 </literallayout>
660 The JSON data for this query is returned in a single line.
661 In the previous example the line has been artificially split for readability.
662 </para>
663 </section>
664 </section>
665
666 <section id='toaster-useful-commands'>
667 <title>Useful Commands</title>
668
669 <para>
670 In addition to the web user interface and the scripts that start
671 and stop Toaster, command-line commands exist through the
672 <filename>manage.py</filename> management script.
673 You can find general documentation on
674 <filename>manage.py</filename> at the
675 <ulink url='https://docs.djangoproject.com/en/1.7/topics/settings/'>Django</ulink>
676 site.
677 However, several <filename>manage.py</filename> commands have been
678 created that are specific to Toaster and are used to control
679 configuration and back-end tasks.
680 You can locate these commands in the
681 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
682 (e.g. <filename>poky</filename>) at
683 <filename>bitbake/lib/manage.py</filename>.
684 This section documents those commands.
685 <note><title>Notes</title>
686 <itemizedlist>
687 <listitem><para>
688 When using <filename>manage.py</filename> commands given
689 a default configuration, you must be sure that your
690 working directory is set to the
691 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
692 Using <filename>manage.py</filename> commands from the
693 Build Directory allows Toaster to find the
694 <filename>toaster.sqlite</filename> file, which is located
695 in the Build Directory.
696 </para></listitem>
697 <listitem><para>
698 For non-default database configurations, it is possible
699 that you can use <filename>manage.py</filename> commands
700 from a directory other than the Build Directory.
701 To do so, the
702 <filename>toastermain/settings.py</filename> file must be
703 configured to point to the correct database backend.
704 </para></listitem>
705 </itemizedlist>
706 </note>
707 </para>
708
709 <section id='toaster-command-buildslist'>
710 <title><filename>buildslist</filename></title>
711
712 <para>
713 The <filename>buildslist</filename> command lists all builds
714 that Toaster has recorded.
715 Access the command as follows:
716 <literallayout class='monospaced'>
717 $ bitbake/lib/toaster/manage.py buildslist
718 </literallayout>
719 The command returns a list, which includes numeric
720 identifications, of the builds that Toaster has recorded in the
721 current database.
722 </para>
723
724 <para>
725 You need to run the <filename>buildslist</filename> command
726 first to identify existing builds in the database before
727 using the
728 <link linkend='toaster-command-builddelete'><filename>builddelete</filename></link>
729 command.
730 Here is an example that assumes default repository and build
731 directory names:
732 <literallayout class='monospaced'>
733 $ cd ~/poky/build
734 $ python ../bitbake/lib/toaster/manage.py buildslist
735 </literallayout>
736 If your Toaster database had only one build, the above
737 <filename>buildslist</filename> command would return something
738 like the following:
739 <literallayout class='monospaced'>
740 1: qemux86 poky core-image-minimal
741 </literallayout>
742 </para>
743 </section>
744
745 <section id='toaster-command-builddelete'>
746 <title><filename>builddelete</filename></title>
747
748 <para>
749 The <filename>builddelete</filename> command deletes data
750 associated with a build.
751 Access the command as follows:
752 <literallayout class='monospaced'>
753 $ bitbake/lib/toaster/manage.py builddelete <replaceable>build_id</replaceable>
754 </literallayout>
755 The command deletes all the build data for the specified
756 <replaceable>build_id</replaceable>.
757 This command is useful for removing old and unused data from
758 the database.
759 </para>
760
761 <para>
762 Prior to running the <filename>builddelete</filename>
763 command, you need to get the ID associated with builds
764 by using the
765 <link linkend='toaster-command-buildslist'><filename>buildslist</filename></link>
766 command.
767 </para>
768 </section>
769
770 <section id='toaster-command-perf'>
771 <title><filename>perf</filename></title>
772
773 <para>
774 The <filename>perf</filename> command measures Toaster
775 performance.
776 Access the command as follows:
777 <literallayout class='monospaced'>
778 $ bitbake/lib/toaster/manage.py perf
779 </literallayout>
780 The command is a sanity check that returns page loading
781 times in order to identify performance problems.
782 </para>
783 </section>
784
785 <section id='toaster-command-checksettings'>
786 <title><filename>checksettings</filename></title>
787
788 <para>
789 The <filename>checksettings</filename> command verifies
790 existing Toaster settings.
791 Access the command as follows:
792 <literallayout class='monospaced'>
793 $ bitbake/lib/toaster/manage.py checksettings
794 </literallayout>
795 Toaster uses settings that are based on the
796 database to configure the building tasks.
797 The <filename>checksettings</filename> command verifies that
798 the database settings are valid in the sense that they have
799 the minimal information needed to start a build.
800 </para>
801
802 <para>
803 In order for the <filename>checksettings</filename> command
804 to work, the database must be correctly set up and not have
805 existing data.
806 To be sure the database is ready, you can run the following:
807 <literallayout class='monospaced'>
808 $ bitbake/lib/toaster/mana​ge.py syncdb
809 $ bitbake/lib/toaster/mana​ge.py migrate orm
810 $ bitbake/lib/toaster/mana​ge.py migrate bldcontrol
811 </literallayout>
812 After running these commands, you can run the
813 <filename>checksettings</filename> command.
814 </para>
815 </section>
816
817 <section id='toaster-command-runbuilds'>
818 <title><filename>runbuilds</filename></title>
819
820 <para>
821 The <filename>runbuilds</filename> command launches
822 scheduled builds.
823 Access the command as follows:
824 <literallayout class='monospaced'>
825 $ bitbake/lib/toaster/manage.py runbuilds
826 </literallayout>
827 The <filename>runbuilds</filename> command checks if
828 scheduled builds exist in the database and then launches them
829 per schedule.
830 The command returns after the builds start but before they
831 complete.
832 The Toaster Logging Interface records and updates the database
833 when the builds complete.
834 </para>
835 </section>
836 </section>
837</chapter>
diff --git a/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
deleted file mode 100644
index f555745923..0000000000
--- a/documentation/toaster-manual/toaster-manual-setup-and-use.xml
+++ /dev/null
@@ -1,844 +0,0 @@
1<!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<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='toaster-manual-setup-and-use'>
7
8<title>Setting Up and Using Toaster</title>
9
10 <section id='starting-toaster-for-local-development'>
11 <title>Starting Toaster for Local Development</title>
12
13 <para>
14 Once you have set up the Yocto Project and installed the
15 Toaster system dependencies as described in the
16 "<link linkend='toaster-manual-start'>Preparing to Use Toaster</link>"
17 chapter, you are ready to start Toaster.
18 </para>
19
20 <para>
21 Navigate to the root of your
22 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
23 (e.g. <filename>poky</filename>):
24 <literallayout class='monospaced'>
25 $ cd poky
26 </literallayout>
27 Once in that directory, source the build environment script:
28 <literallayout class='monospaced'>
29 $ source oe-init-build-env
30 </literallayout>
31 Next, from the build directory (e.g.
32 <filename>poky/build</filename>), start Toaster using this
33 command:
34 <literallayout class='monospaced'>
35 $ source toaster start
36 </literallayout>
37 You can now run your builds from the command line, or with
38 Toaster as explained in section
39 "<link linkend='using-the-toaster-web-interface'>Using the Toaster Web Interface</link>".
40 </para>
41
42 <para>
43 To access the Toaster web interface, open your favorite
44 browser and enter the following:
45 <literallayout class='monospaced'>
46 http://127.0.0.1:8000
47 </literallayout>
48 </para>
49 </section>
50
51 <section id='setting-a-different-port'>
52 <title>Setting a Different Port</title>
53
54 <para>
55 By default, Toaster starts on port 8000.
56 You can use the <filename>WEBPORT</filename> parameter to
57 set a different port.
58 For example, the following command sets the port to "8400":
59 <literallayout class='monospaced'>
60 $ source toaster start webport=8400
61 </literallayout>
62 </para>
63 </section>
64
65 <section id='setting-up-toaster-without-a-web-server'>
66 <title>Setting Up Toaster Without a Web Server</title>
67
68 <para>
69 You can start a Toaster environment without starting its
70 web server. This is useful for the following:
71 <itemizedlist>
72 <listitem><para>
73 Capturing a command-line build's statistics into
74 the Toaster database for examination later.
75 </para></listitem>
76 <listitem><para>
77 Capturing a command-line build's statistics when
78 the Toaster server is already running.
79 </para></listitem>
80 <listitem><para>
81 Having one instance of the Toaster web server
82 track and capture multiple command-line builds,
83 where each build is started in its own "noweb"
84 Toaster environment.
85 </para></listitem>
86 </itemizedlist>
87 The following commands show how to start a Toaster environment
88 without starting its web server, perform BitBake operations,
89 and then shut down the Toaster environment.
90 Once the build is complete, you can close the Toaster environment.
91 Before closing the environment, however, you should allow a few
92 minutes to ensure the complete transfer of its BitBake build
93 statistics to the Toaster database.
94 If you have a separate Toaster web server instance running, you
95 can watch this command-line build's progress and examine the
96 results as soon as they are posted:
97 <literallayout class='monospaced'>
98 $ source toaster start noweb
99 $ bitbake <replaceable>target</replaceable>
100 $ source toaster stop
101 </literallayout>
102 </para>
103 </section>
104
105 <section id='setting-up-toaster-without-a-build-server'>
106 <title>Setting Up Toaster Without a Build Server</title>
107
108 <para>
109 You can start a Toaster environment with the
110 "New Projects" feature disabled.
111 Doing so is useful for the following:
112 <itemizedlist>
113 <listitem><para>
114 Sharing your build results over the web server while
115 blocking others from starting builds on your host.
116 </para></listitem>
117 <listitem><para>
118 Allowing only local command-line builds to be captured
119 into the Toaster database.
120 </para></listitem>
121 </itemizedlist>
122 Use the following command to set up Toaster without a
123 build server:
124 <literallayout class='monospaced'>
125 $ source toaster start nobuild webport=<replaceable>port</replaceable>
126 </literallayout>
127 </para>
128 </section>
129
130 <section id='setting-up-external-access'>
131 <title>Setting up External Access</title>
132
133 <para>
134 By default, Toaster binds to the loop back address
135 (i.e. localhost), which does not allow access from
136 external hosts. To allow external access, use the
137 <filename>WEBPORT</filename> parameter to open an
138 address that connects to the network, specifically the
139 IP address that your NIC uses to connect to the network.
140 You can also bind to all IP addresses the computer
141 supports by using the shortcut
142 "0.0.0.0:<replaceable>port</replaceable>".
143 </para>
144
145 <para>
146 The following example binds to all IP addresses on the
147 host:
148 <literallayout class='monospaced'>
149 $ source toaster start webport=0.0.0.0:8400
150 </literallayout>
151 This example binds to a specific IP address on the host's
152 NIC:
153 <literallayout class='monospaced'>
154 $ source toaster start webport=192.168.1.1:8400
155 </literallayout>
156 </para>
157 </section>
158
159 <section id='the-directory-for-cloning-layers'>
160 <title>The Directory for Cloning Layers</title>
161
162 <para>
163 Toaster creates a <filename>_toaster_clones</filename>
164 directory inside your Source Directory
165 (i.e. <filename>poky</filename>) to clone any layers
166 needed for your builds.
167 </para>
168
169 <para>
170 Alternatively, if you would like all of your Toaster related
171 files and directories to be in a particular location other than
172 the default, you can set the <filename>TOASTER_DIR</filename>
173 environment variable, which takes precedence over your current
174 working directory.
175 Setting this environment variable causes Toaster to create and use
176 <filename>$TOASTER_DIR./_toaster_clones</filename>.
177 </para>
178 </section>
179
180 <section id='toaster-the-build-directory'>
181 <title>The Build Directory</title>
182
183 <para>
184 Toaster creates a build directory within your Source
185 Directory (e.g. <filename>poky</filename>) to execute
186 the builds.
187 </para>
188
189 <para>
190 Alternatively, if you would like all of your Toaster related files
191 and directories to be in a particular location, you can set
192 the <filename>TOASTER_DIR</filename> environment variable,
193 which takes precedence over your current working directory.
194 Setting this environment variable causes Toaster to use
195 <filename>$TOASTER_DIR/build</filename> as the build directory.
196 </para>
197 </section>
198
199 <section id='toaster-creating-a-django-super-user'>
200 <title>Creating a Django Superuser</title>
201
202 <para>
203 Toaster is built on the
204 <ulink url='https://www.djangoproject.com/'>Django framework</ulink>.
205 Django provides an administration interface you can use
206 to edit Toaster configuration parameters.
207 </para>
208
209 <para>
210 To access the Django administration interface, you must
211 create a superuser by following these steps:
212 <orderedlist>
213 <listitem><para>
214 If you used <filename>pip3</filename>, which is
215 recommended, to set up the Toaster system dependencies,
216 you need be sure the local user path is in your
217 <filename>PATH</filename> list.
218 To append the pip3 local user path, use the following
219 command:
220 <literallayout class='monospaced'>
221 $ export PATH=$PATH:$HOME/.local/bin
222 </literallayout>
223 </para></listitem>
224 <listitem><para>
225 From the directory containing the Toaster database,
226 which by default is the
227 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
228 invoke the <filename>createsuperuser</filename> command
229 from <filename>manage.py</filename>:
230 <literallayout class='monospaced'>
231 $ cd ~/poky/build
232 $ ../bitbake/lib/toaster/manage.py createsuperuser
233 </literallayout>
234 </para></listitem>
235 <listitem><para>
236 Django prompts you for the username, which you need to
237 provide.
238 </para></listitem>
239 <listitem><para>
240 Django prompts you for an email address, which is
241 optional.
242 </para></listitem>
243 <listitem><para>
244 Django prompts you for a password, which you must provide.
245 </para></listitem>
246 <listitem><para>
247 Django prompts you to re-enter your password for verification.
248 </para></listitem>
249 </orderedlist>
250 After completing these steps, the following confirmation message
251 appears:
252 <literallayout class='monospaced'>
253 Superuser created successfully.
254 </literallayout>
255 </para>
256
257 <para>
258 Creating a superuser allows you to access the Django administration
259 interface through a browser.
260 The URL for this interface is the same as the URL used for the
261 Toaster instance with "/admin" on the end.
262 For example, if you are running Toaster locally, use the
263 following URL:
264 <literallayout class='monospaced'>
265 http://127.0.0.1:8000/admin
266 </literallayout>
267 You can use the Django administration interface to set Toaster
268 configuration parameters such as the build directory, layer sources,
269 default variable values, and BitBake versions.
270 </para>
271 </section>
272
273 <section id='toaster-setting-up-a-production-instance-of-toaster'>
274 <title>Setting Up a Production Instance of Toaster</title>
275
276 <para>
277 You can use a production instance of Toaster to share the
278 Toaster instance with remote users, multiple users, or both.
279 The production instance is also the setup that can handle
280 heavier loads on the web service.
281 Use the instructions in the following sections to set up
282 Toaster to run builds through the Toaster web interface.
283 </para>
284
285 <section id='toaster-production-instance-requirements'>
286 <title>Requirements</title>
287
288 <para>
289 Be sure you meet the following requirements:
290 <note>
291 You must comply with all Apache,
292 <filename>mod-wsgi</filename>, and Mysql requirements.
293 </note>
294 <itemizedlist>
295 <listitem><para>
296 Have all the build requirements as described in the
297 "<link linkend='toaster-manual-start'>Preparing to Use Toaster</link>"
298 chapter.
299 </para></listitem>
300 <listitem><para>
301 Have an Apache webserver.
302 </para></listitem>
303 <listitem><para>
304 Have <filename>mod-wsgi</filename> for the Apache
305 webserver.
306 </para></listitem>
307 <listitem><para>
308 Use the Mysql database server.
309 </para></listitem>
310 <listitem><para>
311 If you are using Ubuntu 16.04, run the following:
312 <literallayout class='monospaced'>
313 $ sudo apt-get install apache2 libapache2-mod-wsgi-py3 mysql-server python3-pip libmysqlclient-dev
314 </literallayout>
315 </para></listitem>
316 <listitem><para>
317 If you are using Fedora 24 or a RedHat distribution, run
318 the following:
319 <literallayout class='monospaced'>
320 $ sudo dnf install httpd python3-mod_wsgi python3-pip mariadb-server mariadb-devel python3-devel
321 </literallayout>
322 </para></listitem>
323 <listitem><para>
324 If you are using openSUSE Leap 42.1, run
325 the following:
326 <literallayout class='monospaced'>
327 $ sudo zypper install apache2 apache2-mod_wsgi-python3 python3-pip mariadb mariadb-client python3-devel
328 </literallayout>
329 </para></listitem>
330 </itemizedlist>
331 </para>
332 </section>
333
334 <section id='toaster-installation-steps'>
335 <title>Installation</title>
336
337 <para>
338 Perform the following steps to install Toaster:
339 <orderedlist>
340 <listitem><para>
341 Create toaster user and set its home directory to
342 <filename>/var/www/toaster</filename>:
343 <literallayout class='monospaced'>
344 $ sudo /usr/sbin/useradd toaster -md /var/www/toaster -s /bin/false
345 $ sudo su - toaster -s /bin/bash
346 </literallayout>
347 </para></listitem>
348 <listitem><para>
349 Checkout a copy of <filename>poky</filename>
350 into the web server directory.
351 You will be using <filename>/var/www/toaster</filename>:
352 <literallayout class='monospaced'>
353 $ git clone git://git.yoctoproject.org/poky
354 $ git checkout &DISTRO_NAME_NO_CAP;
355 </literallayout>
356 </para></listitem>
357 <listitem><para>
358 Install Toaster
359 dependencies using the --user flag which
360 keeps the Python packages
361 isolated from your system-provided packages:
362 <literallayout class='monospaced'>
363 $ cd /var/www/toaster/
364 $ pip3 install --user -r ./poky/bitbake/toaster-requirements.txt
365 $ pip3 install --user mysqlclient
366 </literallayout>
367 <note>
368 Isolating these packages is not required but is
369 recommended.
370 Alternatively, you can use your operating system's
371 package manager to install the packages.
372 </note>
373 </para></listitem>
374 <listitem><para>
375 Configure Toaster by editing
376 <filename>/var/www/toaster/poky/bitbake/lib/toaster/toastermain/settings.py</filename>
377 as follows:
378 <itemizedlist>
379 <listitem><para>
380 Edit the
381 <ulink url='https://docs.djangoproject.com/en/1.11/ref/settings/#databases'>DATABASES</ulink>
382 settings:
383 <literallayout class='monospaced'>
384 DATABASES = {
385 'default': {
386 'ENGINE': 'django.db.backends.mysql',
387 'NAME': 'toaster_data',
388 'USER': 'toaster',
389 'PASSWORD': 'yourpasswordhere',
390 'HOST': 'localhost',
391 'PORT': '3306',
392 }
393 }
394 </literallayout>
395 </para></listitem>
396 <listitem><para>
397 Edit the
398 <ulink url='https://docs.djangoproject.com/en/1.11/ref/settings/#std:setting-SECRET_KEY'>SECRET_KEY</ulink>:
399 <literallayout class='monospaced'>
400 SECRET_KEY = '<replaceable>your_secret_key</replaceable>'
401 </literallayout>
402 </para></listitem>
403 <listitem><para>
404 Edit the
405 <ulink url='https://docs.djangoproject.com/en/1.11/ref/settings/#std:setting-STATIC_ROOT'>STATIC_ROOT</ulink>:
406 <literallayout class='monospaced'>
407 STATIC_ROOT = '/var/www/toaster/static_files/'
408 </literallayout>
409 </para></listitem>
410 </itemizedlist>
411 </para></listitem>
412 <listitem><para>
413 Add the database and user to the <filename>mysql</filename>
414 server defined earlier:
415 <literallayout class='monospaced'>
416 $ mysql -u root -p
417 mysql> CREATE DATABASE toaster_data;
418 mysql> CREATE USER 'toaster'@'localhost' identified by 'yourpasswordhere';
419 mysql> GRANT all on toaster_data.* to 'toaster'@'localhost';
420 mysql> quit
421 </literallayout>
422 </para></listitem>
423 <listitem><para>
424 Get Toaster to create the database schema,
425 default data, and gather the statically-served files:
426 <literallayout class='monospaced'>
427 $ cd /var/www/toaster/poky/
428 $ ./bitbake/lib/toaster/manage.py migrate
429 $ TOASTER_DIR=`pwd` TEMPLATECONF='poky' \
430 ./bitbake/lib/toaster/manage.py checksettings
431 $ ./bitbake/lib/toaster/manage.py collectstatic
432 </literallayout>
433 In the previous example, from the <filename>poky</filename>
434 directory, the <filename>migrate</filename> command
435 ensures the database schema changes have propagated
436 correctly (i.e. migrations).
437 The next line sets the Toaster root directory
438 <filename>TOASTER_DIR</filename> and the location
439 of the Toaster configuration file
440 <filename>TOASTER_CONF</filename>, which is relative to
441 <filename>TOASTER_DIR</filename>.
442 The <filename>TEMPLATECONF</filename> value reflects the
443 contents of <filename>poky/.templateconf</filename>, and
444 by default, should include the string "poky".
445 For more information on the Toaster configuration
446 file, see the
447 "<link linkend='configuring-toaster'>Configuring Toaster</link>"
448 section.</para>
449
450 <para>This line also runs the <filename>checksettings</filename>
451 command, which configures the location of the Toaster
452 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
453 The Toaster root directory <filename>TOASTER_DIR</filename>
454 determines where the Toaster build directory
455 is created on the file system.
456 In the example above,
457 <filename>TOASTER_DIR</filename> is set as follows:
458 <literallayout class="monospaced">
459 /var/www/toaster/poky
460 </literallayout>
461 This setting causes the Toaster build directory to be:
462 <literallayout class="monospaced">
463 /var/www/toaster/poky/build
464 </literallayout></para>
465
466 <para>Finally, the <filename>collectstatic</filename> command
467 is a Django framework command that collects all the
468 statically served files into a designated directory to
469 be served up by the Apache web server as defined by
470 <filename>STATIC_ROOT</filename>.
471 </para></listitem>
472 <listitem><para>
473 Test and/or use the Mysql integration with Toaster's
474 Django web server.
475 At this point, you can start up the normal Toaster
476 Django web server with the Toaster database in Mysql.
477 You can use this web server to confirm that the database
478 migration and data population from the Layer Index is
479 complete.</para>
480
481 <para>To start the default Toaster Django web server with
482 the Toaster database now in Mysql, use the standard
483 start commands:
484 <literallayout class='monospaced'>
485 $ source oe-init-build-env
486 $ source toaster start
487 </literallayout>
488 Additionally, if Django is sufficient for your requirements,
489 you can use it for your release system and migrate later
490 to Apache as your requirements change.
491 </para></listitem>
492 <listitem><para>
493 Add an Apache configuration file for Toaster to your Apache web
494 server's configuration directory.
495 If you are using Ubuntu or Debian, put the file here:
496 <literallayout class='monospaced'>
497 /etc/apache2/conf-available/toaster.conf
498 </literallayout>
499 If you are using Fedora or RedHat, put it here:
500 <literallayout class='monospaced'>
501 /etc/httpd/conf.d/toaster.conf
502 </literallayout>
503 If you are using OpenSUSE, put it here:
504 <literallayout class='monospaced'>
505 /etc/apache2/conf.d/toaster.conf
506 </literallayout>
507 Following is a sample Apache configuration for Toaster
508 you can follow:
509 <literallayout class='monospaced'>
510 Alias /static /var/www/toaster/static_files
511 &lt;Directory /var/www/toaster/static_files&gt;
512 &lt;IfModule mod_access_compat.c&gt;
513 Order allow,deny
514 Allow from all
515 &lt;/IfModule&gt;
516 &lt;IfModule !mod_access_compat.c&gt;
517 Require all granted
518 &lt;/IfModule&gt;
519 &lt;/Directory&gt;
520
521 &lt;Directory /var/www/toaster/poky/bitbake/lib/toaster/toastermain&gt;
522 &lt;Files "wsgi.py"&gt;
523 Require all granted
524 &lt;/Files&gt;
525 &lt;/Directory&gt;
526
527 WSGIDaemonProcess toaster_wsgi python-path=/var/www/toaster/poky/bitbake/lib/toaster:/var/www/toaster/.local/lib/python3.4/site-packages
528
529 WSGIScriptAlias / "/var/www/toaster/poky/bitbake/lib/toaster/toastermain/wsgi.py"
530 &lt;Location /&gt;
531 WSGIProcessGroup toaster_wsgi
532 &lt;/Location&gt;
533 </literallayout>
534 If you are using Ubuntu or Debian,
535 you will need to enable the config and module for Apache:
536 <literallayout class='monospaced'>
537 $ sudo a2enmod wsgi
538 $ sudo a2enconf toaster
539 $ chmod +x bitbake/lib/toaster/toastermain/wsgi.py
540 </literallayout>
541 Finally, restart Apache to make sure all new configuration
542 is loaded.
543 For Ubuntu, Debian, and OpenSUSE use:
544 <literallayout class='monospaced'>
545 $ sudo service apache2 restart
546 </literallayout>
547 For Fedora and RedHat use:
548 <literallayout class='monospaced'>
549 $ sudo service httpd restart
550 </literallayout>
551 </para></listitem>
552 <listitem><para>
553 Prepare the systemd service to run Toaster builds.
554 Here is a sample configuration file for the service:
555 <literallayout class='monospaced'>
556 [Unit]
557 Description=Toaster runbuilds
558
559 [Service]
560 Type=forking
561 User=toaster
562 ExecStart=/usr/bin/screen -d -m -S runbuilds /var/www/toaster/poky/bitbake/lib/toaster/runbuilds-service.sh start
563 ExecStop=/usr/bin/screen -S runbuilds -X quit
564 WorkingDirectory=/var/www/toaster/poky
565
566 [Install]
567 WantedBy=multi-user.target
568 </literallayout>
569 Prepare the <filename>runbuilds-service.sh</filename>
570 script that you need to place in the
571 <filename>/var/www/toaster/poky/bitbake/lib/toaster/</filename>
572 directory by setting up executable permissions:
573 <literallayout class='monospaced'>
574 #!/bin/bash
575
576 #export http_proxy=http://proxy.host.com:8080
577 #export https_proxy=http://proxy.host.com:8080
578 #export GIT_PROXY_COMMAND=$HOME/bin/gitproxy
579
580 cd ~/poky/
581 source ./oe-init-build-env build
582 source ../bitbake/bin/toaster $1 noweb
583 [ "$1" == 'start' ] &amp;&amp; /bin/bash
584 </literallayout>
585 </para></listitem>
586 <listitem><para>
587 Run the service:
588 <literallayout class='monospaced'>
589 # service runbuilds start
590 </literallayout>
591 Since the service is running in a detached screen
592 session, you can attach to it using this command:
593 <literallayout class='monospaced'>
594 $ sudo su - toaster
595 $ screen -rS runbuilds
596 </literallayout>
597 You can detach from the service again using "Ctrl-a"
598 followed by "d" key combination.
599 </para></listitem>
600 </orderedlist>
601 You can now open up a browser and start using Toaster.
602 </para>
603 </section>
604 </section>
605
606 <section id='using-the-toaster-web-interface'>
607 <title>Using the Toaster Web Interface</title>
608
609 <para>
610 The Toaster web interface allows you to do the following:
611 <itemizedlist>
612 <listitem><para>
613 Browse published layers in the
614 <ulink url='http://layers.openembedded.org'>OpenEmbedded Layer Index</ulink>
615 that are available for your selected version of the build
616 system.
617 </para></listitem>
618 <listitem><para>
619 Import your own layers for building.
620 </para></listitem>
621 <listitem><para>
622 Add and remove layers from your configuration.
623 </para></listitem>
624 <listitem><para>
625 Set configuration variables.
626 </para></listitem>
627 <listitem><para>
628 Select a target or multiple targets to build.
629 </para></listitem>
630 <listitem><para>
631 Start your builds.
632 </para></listitem>
633 <listitem><para>
634 See what was built (recipes and packages) and what
635 packages were installed into your final image.
636 </para></listitem>
637 <listitem><para>
638 Browse the directory structure of your image.
639 </para></listitem>
640 <listitem><para>
641 See the value of all variables in your build configuration,
642 and which files set each value.
643 </para></listitem>
644 <listitem><para>
645 Examine error, warning and trace messages to aid in
646 debugging.
647 </para></listitem>
648 <listitem><para>
649 See information about the BitBake tasks executed and
650 reused during your build, including those that used
651 shared state.
652 </para></listitem>
653 <listitem><para>
654 See dependency relationships between recipes, packages
655 and tasks.
656 </para></listitem>
657 <listitem><para>
658 See performance information such as build time, task time,
659 CPU usage, and disk I/O.
660 </para></listitem>
661 </itemizedlist>
662 </para>
663
664 <section id='web-interface-videos'>
665 <title>Toaster Web Interface Videos</title>
666
667 <para>
668 Following are several videos that show how to use the Toaster GUI:
669 <itemizedlist>
670 <listitem><para><emphasis>Build Configuration:</emphasis>
671 This
672 <ulink url='https://www.youtube.com/watch?v=qYgDZ8YzV6w'>video</ulink>
673 overviews and demonstrates build configuration for Toaster.
674 </para></listitem>
675 <listitem><para><emphasis>Build Custom Layers:</emphasis>
676 This
677 <ulink url='https://www.youtube.com/watch?v=QJzaE_XjX5c'>video</ulink>
678 shows you how to build custom layers that are used with
679 Toaster.
680 </para></listitem>
681 <listitem><para><emphasis>Toaster Homepage and Table Controls:</emphasis>
682 This
683 <ulink url='https://www.youtube.com/watch?v=QEARDnrR1Xw'>video</ulink>
684 goes over the Toaster entry page, and provides
685 an overview of the data manipulation capabilities of
686 Toaster, which include search, sorting and filtering by
687 different criteria.
688 </para></listitem>
689 <listitem><para><emphasis>Build Dashboard:</emphasis>
690 This
691 <ulink url='https://www.youtube.com/watch?v=KKqHYcnp2gE'>video</ulink>
692 shows you the build dashboard, a page providing an
693 overview of the information available for a selected build.
694 </para></listitem>
695 <listitem><para><emphasis>Image Information:</emphasis>
696 This
697 <ulink url='https://www.youtube.com/watch?v=XqYGFsmA0Rw'>video</ulink>
698 walks through the information Toaster provides
699 about images: packages installed and root file system.
700 </para></listitem>
701 <listitem><para><emphasis>Configuration:</emphasis>
702 This
703 <ulink url='https://www.youtube.com/watch?v=UW-j-T2TzIg'>video</ulink>
704 provides Toaster build configuration information.
705 </para></listitem>
706 <listitem><para><emphasis>Tasks:</emphasis>
707 This
708 <ulink url='https://www.youtube.com/watch?v=D4-9vGSxQtw'>video</ulink>
709 shows the information Toaster provides about the
710 tasks run by the build system.
711 </para></listitem>
712 <listitem><para><emphasis>Recipes and Packages Built:</emphasis>
713 This
714 <ulink url='https://www.youtube.com/watch?v=x-6dx4huNnw'>video</ulink>
715 shows the information Toaster provides about recipes
716 and packages built.
717 </para></listitem>
718 <listitem><para><emphasis>Performance Data:</emphasis>
719 This
720 <ulink url='https://www.youtube.com/watch?v=qWGMrJoqusQ'>video</ulink>
721 shows the build performance data provided by
722 Toaster.
723 </para></listitem>
724 </itemizedlist>
725 </para>
726 </section>
727
728 <section id='a-note-on-the-local-yocto-project-release'>
729 <title>Additional Information About the Local Yocto Project Release</title>
730
731 <para>
732 This section only applies if you have set up Toaster
733 for local development, as explained in the
734 "<link linkend='starting-toaster-for-local-development'>Starting Toaster for Local Development</link>"
735 section.
736 </para>
737
738 <para>
739 When you create a project in Toaster, you will be asked to
740 provide a name and to select a Yocto Project release.
741 One of the release options you will find is called
742 "Local Yocto Project".
743 <imagedata fileref="figures/new-project.png" align="center" width="9in" />
744 </para>
745
746 <para>
747 When you select the "Local Yocto Project" release, Toaster
748 will run your builds using the local Yocto
749 Project clone you have in your computer: the same clone
750 you are using to run Toaster.
751 Unless you manually update
752 this clone, your builds will always use the same Git revision.
753 </para>
754
755 <para>
756 If you select any of the other release options, Toaster
757 will fetch the tip of your selected release from the upstream
758 <ulink url='https://git.yoctoproject.org'>Yocto Project repository</ulink>
759 every time you run a build.
760 Fetching this tip effectively
761 means that if your selected release is updated upstream, the
762 Git revision you are using for your builds will change.
763 If you are doing development locally, you might not want this
764 change to happen.
765 In that case, the "Local Yocto Project"
766 release might be the right choice.
767 </para>
768
769 <para>
770 However, the "Local Yocto Project" release
771 will not provide you with any compatible layers, other than the
772 three core layers that come with the Yocto Project:
773 <itemizedlist>
774 <listitem><para>
775 <ulink url='http://layers.openembedded.org/layerindex/branch/master/layer/openembedded-core/'>openembedded-core</ulink>
776 </para></listitem>
777 <listitem><para>
778 <ulink url='http://layers.openembedded.org/layerindex/branch/master/layer/meta-poky/'>meta-poky</ulink>
779 </para></listitem>
780 <listitem><para>
781 <ulink url='http://layers.openembedded.org/layerindex/branch/master/layer/meta-yocto-bsp/'>meta-yocto-bsp</ulink>
782 </para></listitem>
783 </itemizedlist>
784 <imagedata fileref="figures/compatible-layers.png" align="center" width="9in" />
785 </para>
786
787 <para>
788 If you want to build any other layers, you will need to
789 manually import them into your Toaster project, using the
790 "Import layer" page.
791 <imagedata fileref="figures/import-layer.png" align="center" width="9in" />
792 </para>
793
794 </section>
795
796 <section id='toaster-web-interface-preferred-version'>
797 <title>Building a Specific Recipe Given Multiple Versions</title>
798
799 <para>
800 Occasionally, a layer might provide more than one version of
801 the same recipe.
802 For example, the <filename>openembedded-core</filename> layer
803 provides two versions of the <filename>bash</filename> recipe
804 (i.e. 3.2.48 and 4.3.30-r0) and two versions of the
805 <filename>which</filename> recipe (i.e. 2.21 and 2.18).
806 The following figure shows this exact scenario:
807 <imagedata fileref="figures/bash-oecore.png" align="center" width="9in" depth="6in" />
808 </para>
809
810 <para>
811 By default, the OpenEmbedded build system builds one of the
812 two recipes.
813 For the <filename>bash</filename> case, version 4.3.30-r0 is
814 built by default.
815 Unfortunately, Toaster as it exists, is not able to override
816 the default recipe version.
817 If you would like to build bash 3.2.48, you need to set the
818 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink>
819 variable.
820 You can do so from Toaster, using the "Add variable" form,
821 which is available in the "BitBake variables" page of the
822 project configuration section as shown in the following screen:
823 <imagedata fileref="figures/add-variable.png" align="center" width="9in" depth="6in" />
824 </para>
825
826 <para>
827 To specify <filename>bash</filename> 3.2.48 as the version to build,
828 enter "PREFERRED_VERSION_bash" in the "Variable" field, and "3.2.48"
829 in the "Value" field.
830 Next, click the "Add variable" button:
831 <imagedata fileref="figures/set-variable.png" align="center" width="9in" depth="6in" />
832 </para>
833
834 <para>
835 After clicking the "Add variable" button, the settings for
836 <filename>PREFERRED_VERSION</filename> are added to the bottom
837 of the BitBake variables list.
838 With these settings, the OpenEmbedded build system builds the
839 desired version of the recipe rather than the default version:
840 <imagedata fileref="figures/variable-added.png" align="center" width="9in" depth="6in" />
841 </para>
842 </section>
843 </section>
844</chapter>
diff --git a/documentation/toaster-manual/toaster-manual-start.xml b/documentation/toaster-manual/toaster-manual-start.xml
deleted file mode 100644
index 8a857006e5..0000000000
--- a/documentation/toaster-manual/toaster-manual-start.xml
+++ /dev/null
@@ -1,116 +0,0 @@
1<!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<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='toaster-manual-start'>
7
8<title>Preparing to Use Toaster</title>
9
10 <para>
11 This chapter describes how you need to prepare your system in order to
12 use Toaster.
13 </para>
14
15 <section id='toaster-setting-up-the-basic-system-requirements'>
16 <title>Setting Up the Basic System Requirements</title>
17
18 <para>
19 Before you can use Toaster, you need to first set up your
20 build system to run the Yocto Project.
21 To do this, follow the instructions in the
22 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>"
23 section of the Yocto Project Development Tasks
24 Manual.
25 For Ubuntu/Debian, you might also need to do an additional install
26 of pip3.
27 <literallayout class='monospaced'>
28 $ sudo apt-get install python3-pip
29 </literallayout>
30 </para>
31 </section>
32
33 <section id='toaster-establishing-toaster-system-dependencies'>
34 <title>Establishing Toaster System Dependencies</title>
35
36 <para>
37 Toaster requires extra Python dependencies in order to run.
38 A Toaster requirements file named
39 <filename>toaster-requirements.txt</filename> defines the
40 Python dependencies.
41 The requirements file is located in the
42 <filename>bitbake</filename> directory, which is located in the
43 root directory of the
44 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
45 (e.g. <filename>poky/bitbake/toaster-requirements.txt</filename>).
46 The dependencies appear in a <filename>pip</filename>,
47 install-compatible format.
48 </para>
49
50 <section id='toaster-load-packages'>
51 <title>Install Toaster Packages</title>
52
53 <para>
54 You need to install the packages that Toaster requires.
55 Use this command:
56 <literallayout class='monospaced'>
57 $ pip3 install --user -r bitbake/toaster-requirements.txt
58 </literallayout>
59 The previous command installs the necessary Toaster modules
60 into a local python 3 cache in your
61 <filename>$HOME</filename> directory.
62 The caches is actually located in
63 <filename>$HOME/.local</filename>.
64 To see what packages have been installed into your
65 <filename>$HOME</filename> directory, do the following:
66 <literallayout class='monospaced'>
67 $ pip3 list installed --local
68 </literallayout>
69 If you need to remove something, the following works:
70 <literallayout class='monospaced'>
71 $ pip3 uninstall PackageNameToUninstall
72 </literallayout>
73 </para>
74 </section>
75
76<!-- Commenting this section out for now in case it needs to be used again.
77
78 <section id='toaster-install-daemon'>
79 <title>Install <filename>daemon</filename></title>
80
81 <para>
82 Toaster depends on
83 <ulink url='http://www.libslack.org/daemon/'><filename>daemon</filename></ulink>.
84 Depending on your distribution, how you install
85 <filename>daemon</filename> differs:
86 <itemizedlist>
87 <listitem><para><emphasis>Debian-Based Systems:</emphasis>
88 If you are running a Debian-based distribution,
89 install <filename>daemon</filename> using the
90 following command:
91 <literallayout class='monospaced'>
92 $ sudo apt-get install daemon​
93 </literallayout>
94 </para></listitem>
95 <listitem><para><emphasis>Non-Debian-Based Systems:</emphasis>
96 If you are not running a Debian-based distribution
97 (Redhat-based distribution such as Fedora),
98 you need to download ​the file relevant to the
99 architecture and then install
100 <filename>daemon</filename> manually.
101 Following are the commands for 64-bit distributions:
102 <literallayout class='monospaced'>
103 $ wget http://libslack.org/daemon/download/daemon-0.6.4-1.x86_64.rpm
104 $ sudo rpm -i daemon-0.6.4-1.x86_64.rpm
105 </literallayout>
106 Here are the commands for a 32-bit distribution:
107 <literallayout class='monospaced'>
108 $ wget http://libslack.org/daemon/download/daemon-0.6.4-1.i686.rpm
109 $ sudo rpm -i ​daemon-0.6.4-1.i686.rpm​
110 </literallayout>
111 </para></listitem>
112 </itemizedlist>
113 </para>
114 </section> -->
115 </section>
116</chapter>
diff --git a/documentation/toaster-manual/toaster-manual-style.css b/documentation/toaster-manual/toaster-manual-style.css
deleted file mode 100644
index a7f430df05..0000000000
--- a/documentation/toaster-manual/toaster-manual-style.css
+++ /dev/null
@@ -1,987 +0,0 @@
1/*
2
3 SPDX-License-Identifier: CC-BY-2.0-UK
4
5 Generic XHTML / DocBook XHTML CSS Stylesheet.
6
7 Browser wrangling and typographic design by
8 Oyvind Kolas / pippin@gimp.org
9
10 Customised for Poky by
11 Matthew Allum / mallum@o-hand.com
12
13 Thanks to:
14 Liam R. E. Quin
15 William Skaggs
16 Jakub Steiner
17
18 Structure
19 ---------
20
21 The stylesheet is divided into the following sections:
22
23 Positioning
24 Margins, paddings, width, font-size, clearing.
25 Decorations
26 Borders, style
27 Colors
28 Colors
29 Graphics
30 Graphical backgrounds
31 Nasty IE tweaks
32 Workarounds needed to make it work in internet explorer,
33 currently makes the stylesheet non validating, but up until
34 this point it is validating.
35 Mozilla extensions
36 Transparency for footer
37 Rounded corners on boxes
38
39*/
40
41
42 /*************** /
43 / Positioning /
44/ ***************/
45
46body {
47 font-family: Verdana, Sans, sans-serif;
48
49 min-width: 640px;
50 width: 80%;
51 margin: 0em auto;
52 padding: 2em 5em 5em 5em;
53 color: #333;
54}
55
56h1,h2,h3,h4,h5,h6,h7 {
57 font-family: Arial, Sans;
58 color: #00557D;
59 clear: both;
60}
61
62h1 {
63 font-size: 2em;
64 text-align: left;
65 padding: 0em 0em 0em 0em;
66 margin: 2em 0em 0em 0em;
67}
68
69h2.subtitle {
70 margin: 0.10em 0em 3.0em 0em;
71 padding: 0em 0em 0em 0em;
72 font-size: 1.8em;
73 padding-left: 20%;
74 font-weight: normal;
75 font-style: italic;
76}
77
78h2 {
79 margin: 2em 0em 0.66em 0em;
80 padding: 0.5em 0em 0em 0em;
81 font-size: 1.5em;
82 font-weight: bold;
83}
84
85h3.subtitle {
86 margin: 0em 0em 1em 0em;
87 padding: 0em 0em 0em 0em;
88 font-size: 142.14%;
89 text-align: right;
90}
91
92h3 {
93 margin: 1em 0em 0.5em 0em;
94 padding: 1em 0em 0em 0em;
95 font-size: 140%;
96 font-weight: bold;
97}
98
99h4 {
100 margin: 1em 0em 0.5em 0em;
101 padding: 1em 0em 0em 0em;
102 font-size: 120%;
103 font-weight: bold;
104}
105
106h5 {
107 margin: 1em 0em 0.5em 0em;
108 padding: 1em 0em 0em 0em;
109 font-size: 110%;
110 font-weight: bold;
111}
112
113h6 {
114 margin: 1em 0em 0em 0em;
115 padding: 1em 0em 0em 0em;
116 font-size: 110%;
117 font-weight: bold;
118}
119
120.authorgroup {
121 background-color: transparent;
122 background-repeat: no-repeat;
123 padding-top: 256px;
124 background-image: url("figures/toaster-title.png");
125 background-position: left top;
126 margin-top: -256px;
127 padding-right: 50px;
128 margin-left: 0px;
129 text-align: right;
130 width: 740px;
131}
132
133h3.author {
134 margin: 0em 0me 0em 0em;
135 padding: 0em 0em 0em 0em;
136 font-weight: normal;
137 font-size: 100%;
138 color: #333;
139 clear: both;
140}
141
142.author tt.email {
143 font-size: 66%;
144}
145
146.titlepage hr {
147 width: 0em;
148 clear: both;
149}
150
151.revhistory {
152 padding-top: 2em;
153 clear: both;
154}
155
156.toc,
157.list-of-tables,
158.list-of-examples,
159.list-of-figures {
160 padding: 1.33em 0em 2.5em 0em;
161 color: #00557D;
162}
163
164.toc p,
165.list-of-tables p,
166.list-of-figures p,
167.list-of-examples p {
168 padding: 0em 0em 0em 0em;
169 padding: 0em 0em 0.3em;
170 margin: 1.5em 0em 0em 0em;
171}
172
173.toc p b,
174.list-of-tables p b,
175.list-of-figures p b,
176.list-of-examples p b{
177 font-size: 100.0%;
178 font-weight: bold;
179}
180
181.toc dl,
182.list-of-tables dl,
183.list-of-figures dl,
184.list-of-examples dl {
185 margin: 0em 0em 0.5em 0em;
186 padding: 0em 0em 0em 0em;
187}
188
189.toc dt {
190 margin: 0em 0em 0em 0em;
191 padding: 0em 0em 0em 0em;
192}
193
194.toc dd {
195 margin: 0em 0em 0em 2.6em;
196 padding: 0em 0em 0em 0em;
197}
198
199div.glossary dl,
200div.variablelist dl {
201}
202
203.glossary dl dt,
204.variablelist dl dt,
205.variablelist dl dt span.term {
206 font-weight: normal;
207 width: 20em;
208 text-align: right;
209}
210
211.variablelist dl dt {
212 margin-top: 0.5em;
213}
214
215.glossary dl dd,
216.variablelist dl dd {
217 margin-top: -1em;
218 margin-left: 25.5em;
219}
220
221.glossary dd p,
222.variablelist dd p {
223 margin-top: 0em;
224 margin-bottom: 1em;
225}
226
227
228div.calloutlist table td {
229 padding: 0em 0em 0em 0em;
230 margin: 0em 0em 0em 0em;
231}
232
233div.calloutlist table td p {
234 margin-top: 0em;
235 margin-bottom: 1em;
236}
237
238div p.copyright {
239 text-align: left;
240}
241
242div.legalnotice p.legalnotice-title {
243 margin-bottom: 0em;
244}
245
246p {
247 line-height: 1.5em;
248 margin-top: 0em;
249
250}
251
252dl {
253 padding-top: 0em;
254}
255
256hr {
257 border: solid 1px;
258}
259
260
261.mediaobject,
262.mediaobjectco {
263 text-align: center;
264}
265
266img {
267 border: none;
268}
269
270ul {
271 padding: 0em 0em 0em 1.5em;
272}
273
274ul li {
275 padding: 0em 0em 0em 0em;
276}
277
278ul li p {
279 text-align: left;
280}
281
282table {
283 width :100%;
284}
285
286th {
287 padding: 0.25em;
288 text-align: left;
289 font-weight: normal;
290 vertical-align: top;
291}
292
293td {
294 padding: 0.25em;
295 vertical-align: top;
296}
297
298p a[id] {
299 margin: 0px;
300 padding: 0px;
301 display: inline;
302 background-image: none;
303}
304
305a {
306 text-decoration: underline;
307 color: #444;
308}
309
310pre {
311 overflow: auto;
312}
313
314a:hover {
315 text-decoration: underline;
316 /*font-weight: bold;*/
317}
318
319/* This style defines how the permalink character
320 appears by itself and when hovered over with
321 the mouse. */
322
323[alt='Permalink'] { color: #eee; }
324[alt='Permalink']:hover { color: black; }
325
326
327div.informalfigure,
328div.informalexample,
329div.informaltable,
330div.figure,
331div.table,
332div.example {
333 margin: 1em 0em;
334 padding: 1em;
335 page-break-inside: avoid;
336}
337
338
339div.informalfigure p.title b,
340div.informalexample p.title b,
341div.informaltable p.title b,
342div.figure p.title b,
343div.example p.title b,
344div.table p.title b{
345 padding-top: 0em;
346 margin-top: 0em;
347 font-size: 100%;
348 font-weight: normal;
349}
350
351.mediaobject .caption,
352.mediaobject .caption p {
353 text-align: center;
354 font-size: 80%;
355 padding-top: 0.5em;
356 padding-bottom: 0.5em;
357}
358
359.epigraph {
360 padding-left: 55%;
361 margin-bottom: 1em;
362}
363
364.epigraph p {
365 text-align: left;
366}
367
368.epigraph .quote {
369 font-style: italic;
370}
371.epigraph .attribution {
372 font-style: normal;
373 text-align: right;
374}
375
376span.application {
377 font-style: italic;
378}
379
380.programlisting {
381 font-family: monospace;
382 font-size: 80%;
383 white-space: pre;
384 margin: 1.33em 0em;
385 padding: 1.33em;
386}
387
388.tip,
389.warning,
390.caution,
391.note {
392 margin-top: 1em;
393 margin-bottom: 1em;
394
395}
396
397/* force full width of table within div */
398.tip table,
399.warning table,
400.caution table,
401.note table {
402 border: none;
403 width: 100%;
404}
405
406
407.tip table th,
408.warning table th,
409.caution table th,
410.note table th {
411 padding: 0.8em 0.0em 0.0em 0.0em;
412 margin : 0em 0em 0em 0em;
413}
414
415.tip p,
416.warning p,
417.caution p,
418.note p {
419 margin-top: 0.5em;
420 margin-bottom: 0.5em;
421 padding-right: 1em;
422 text-align: left;
423}
424
425.acronym {
426 text-transform: uppercase;
427}
428
429b.keycap,
430.keycap {
431 padding: 0.09em 0.3em;
432 margin: 0em;
433}
434
435.itemizedlist li {
436 clear: none;
437}
438
439.filename {
440 font-size: medium;
441 font-family: Courier, monospace;
442}
443
444
445div.navheader, div.heading{
446 position: absolute;
447 left: 0em;
448 top: 0em;
449 width: 100%;
450 background-color: #cdf;
451 width: 100%;
452}
453
454div.navfooter, div.footing{
455 position: fixed;
456 left: 0em;
457 bottom: 0em;
458 background-color: #eee;
459 width: 100%;
460}
461
462
463div.navheader td,
464div.navfooter td {
465 font-size: 66%;
466}
467
468div.navheader table th {
469 /*font-family: Georgia, Times, serif;*/
470 /*font-size: x-large;*/
471 font-size: 80%;
472}
473
474div.navheader table {
475 border-left: 0em;
476 border-right: 0em;
477 border-top: 0em;
478 width: 100%;
479}
480
481div.navfooter table {
482 border-left: 0em;
483 border-right: 0em;
484 border-bottom: 0em;
485 width: 100%;
486}
487
488div.navheader table td a,
489div.navfooter table td a {
490 color: #777;
491 text-decoration: none;
492}
493
494/* normal text in the footer */
495div.navfooter table td {
496 color: black;
497}
498
499div.navheader table td a:visited,
500div.navfooter table td a:visited {
501 color: #444;
502}
503
504
505/* links in header and footer */
506div.navheader table td a:hover,
507div.navfooter table td a:hover {
508 text-decoration: underline;
509 background-color: transparent;
510 color: #33a;
511}
512
513div.navheader hr,
514div.navfooter hr {
515 display: none;
516}
517
518
519.qandaset tr.question td p {
520 margin: 0em 0em 1em 0em;
521 padding: 0em 0em 0em 0em;
522}
523
524.qandaset tr.answer td p {
525 margin: 0em 0em 1em 0em;
526 padding: 0em 0em 0em 0em;
527}
528.answer td {
529 padding-bottom: 1.5em;
530}
531
532.emphasis {
533 font-weight: bold;
534}
535
536
537 /************* /
538 / decorations /
539/ *************/
540
541.titlepage {
542}
543
544.part .title {
545}
546
547.subtitle {
548 border: none;
549}
550
551/*
552h1 {
553 border: none;
554}
555
556h2 {
557 border-top: solid 0.2em;
558 border-bottom: solid 0.06em;
559}
560
561h3 {
562 border-top: 0em;
563 border-bottom: solid 0.06em;
564}
565
566h4 {
567 border: 0em;
568 border-bottom: solid 0.06em;
569}
570
571h5 {
572 border: 0em;
573}
574*/
575
576.programlisting {
577 border: solid 1px;
578}
579
580div.figure,
581div.table,
582div.informalfigure,
583div.informaltable,
584div.informalexample,
585div.example {
586 border: 1px solid;
587}
588
589
590
591.tip,
592.warning,
593.caution,
594.note {
595 border: 1px solid;
596}
597
598.tip table th,
599.warning table th,
600.caution table th,
601.note table th {
602 border-bottom: 1px solid;
603}
604
605.question td {
606 border-top: 1px solid black;
607}
608
609.answer {
610}
611
612
613b.keycap,
614.keycap {
615 border: 1px solid;
616}
617
618
619div.navheader, div.heading{
620 border-bottom: 1px solid;
621}
622
623
624div.navfooter, div.footing{
625 border-top: 1px solid;
626}
627
628 /********* /
629 / colors /
630/ *********/
631
632body {
633 color: #333;
634 background: white;
635}
636
637a {
638 background: transparent;
639}
640
641a:hover {
642 background-color: #dedede;
643}
644
645
646h1,
647h2,
648h3,
649h4,
650h5,
651h6,
652h7,
653h8 {
654 background-color: transparent;
655}
656
657hr {
658 border-color: #aaa;
659}
660
661
662.tip, .warning, .caution, .note {
663 border-color: #fff;
664}
665
666
667.tip table th,
668.warning table th,
669.caution table th,
670.note table th {
671 border-bottom-color: #fff;
672}
673
674
675.warning {
676 background-color: #f0f0f2;
677}
678
679.caution {
680 background-color: #f0f0f2;
681}
682
683.tip {
684 background-color: #f0f0f2;
685}
686
687.note {
688 background-color: #f0f0f2;
689}
690
691.glossary dl dt,
692.variablelist dl dt,
693.variablelist dl dt span.term {
694 color: #044;
695}
696
697div.figure,
698div.table,
699div.example,
700div.informalfigure,
701div.informaltable,
702div.informalexample {
703 border-color: #aaa;
704}
705
706pre.programlisting {
707 color: black;
708 background-color: #fff;
709 border-color: #aaa;
710 border-width: 2px;
711}
712
713.guimenu,
714.guilabel,
715.guimenuitem {
716 background-color: #eee;
717}
718
719
720b.keycap,
721.keycap {
722 background-color: #eee;
723 border-color: #999;
724}
725
726
727div.navheader {
728 border-color: black;
729}
730
731
732div.navfooter {
733 border-color: black;
734}
735
736
737 /*********** /
738 / graphics /
739/ ***********/
740
741/*
742body {
743 background-image: url("images/body_bg.jpg");
744 background-attachment: fixed;
745}
746
747.navheader,
748.note,
749.tip {
750 background-image: url("images/note_bg.jpg");
751 background-attachment: fixed;
752}
753
754.warning,
755.caution {
756 background-image: url("images/warning_bg.jpg");
757 background-attachment: fixed;
758}
759
760.figure,
761.informalfigure,
762.example,
763.informalexample,
764.table,
765.informaltable {
766 background-image: url("images/figure_bg.jpg");
767 background-attachment: fixed;
768}
769
770*/
771h1,
772h2,
773h3,
774h4,
775h5,
776h6,
777h7{
778}
779
780/*
781Example of how to stick an image as part of the title.
782
783div.article .titlepage .title
784{
785 background-image: url("figures/white-on-black.png");
786 background-position: center;
787 background-repeat: repeat-x;
788}
789*/
790
791div.preface .titlepage .title,
792div.colophon .title,
793div.chapter .titlepage .title,
794div.article .titlepage .title
795{
796}
797
798div.section div.section .titlepage .title,
799div.sect2 .titlepage .title {
800 background: none;
801}
802
803
804h1.title {
805 background-color: transparent;
806 background-repeat: no-repeat;
807 height: 256px;
808 text-indent: -9000px;
809 overflow:hidden;
810}
811
812h2.subtitle {
813 background-color: transparent;
814 text-indent: -9000px;
815 overflow:hidden;
816 width: 0px;
817 display: none;
818}
819
820 /*************************************** /
821 / pippin.gimp.org specific alterations /
822/ ***************************************/
823
824/*
825div.heading, div.navheader {
826 color: #777;
827 font-size: 80%;
828 padding: 0;
829 margin: 0;
830 text-align: left;
831 position: absolute;
832 top: 0px;
833 left: 0px;
834 width: 100%;
835 height: 50px;
836 background: url('/gfx/heading_bg.png') transparent;
837 background-repeat: repeat-x;
838 background-attachment: fixed;
839 border: none;
840}
841
842div.heading a {
843 color: #444;
844}
845
846div.footing, div.navfooter {
847 border: none;
848 color: #ddd;
849 font-size: 80%;
850 text-align:right;
851
852 width: 100%;
853 padding-top: 10px;
854 position: absolute;
855 bottom: 0px;
856 left: 0px;
857
858 background: url('/gfx/footing_bg.png') transparent;
859}
860*/
861
862
863
864 /****************** /
865 / nasty ie tweaks /
866/ ******************/
867
868/*
869div.heading, div.navheader {
870 width:expression(document.body.clientWidth + "px");
871}
872
873div.footing, div.navfooter {
874 width:expression(document.body.clientWidth + "px");
875 margin-left:expression("-5em");
876}
877body {
878 padding:expression("4em 5em 0em 5em");
879}
880*/
881
882 /**************************************** /
883 / mozilla vendor specific css extensions /
884/ ****************************************/
885/*
886div.navfooter, div.footing{
887 -moz-opacity: 0.8em;
888}
889
890div.figure,
891div.table,
892div.informalfigure,
893div.informaltable,
894div.informalexample,
895div.example,
896.tip,
897.warning,
898.caution,
899.note {
900 -moz-border-radius: 0.5em;
901}
902
903b.keycap,
904.keycap {
905 -moz-border-radius: 0.3em;
906}
907*/
908
909table tr td table tr td {
910 display: none;
911}
912
913
914hr {
915 display: none;
916}
917
918table {
919 border: 0em;
920}
921
922 .photo {
923 float: right;
924 margin-left: 1.5em;
925 margin-bottom: 1.5em;
926 margin-top: 0em;
927 max-width: 17em;
928 border: 1px solid gray;
929 padding: 3px;
930 background: white;
931}
932 .seperator {
933 padding-top: 2em;
934 clear: both;
935 }
936
937 #validators {
938 margin-top: 5em;
939 text-align: right;
940 color: #777;
941 }
942 @media print {
943 body {
944 font-size: 8pt;
945 }
946 .noprint {
947 display: none;
948 }
949 }
950
951
952.tip,
953.note {
954 background: #f0f0f2;
955 color: #333;
956 padding: 20px;
957 margin: 20px;
958}
959
960.tip h3,
961.note h3 {
962 padding: 0em;
963 margin: 0em;
964 font-size: 2em;
965 font-weight: bold;
966 color: #333;
967}
968
969.tip a,
970.note a {
971 color: #333;
972 text-decoration: underline;
973}
974
975.footnote {
976 font-size: small;
977 color: #333;
978}
979
980/* Changes the announcement text */
981.tip h3,
982.warning h3,
983.caution h3,
984.note h3 {
985 font-size:large;
986 color: #00557D;
987}
diff --git a/documentation/toaster-manual/toaster-manual.xml b/documentation/toaster-manual/toaster-manual.xml
deleted file mode 100755
index 136b4df964..0000000000
--- a/documentation/toaster-manual/toaster-manual.xml
+++ /dev/null
@@ -1,159 +0,0 @@
1<!DOCTYPE book 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<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<book id='toaster-manual' lang='en'
7 xmlns:xi="http://www.w3.org/2003/XInclude"
8 xmlns="http://docbook.org/ns/docbook"
9 >
10 <bookinfo>
11
12 <mediaobject>
13 <imageobject>
14 <imagedata fileref='figures/toaster-title.png'
15 format='SVG'
16 align='left' scalefit='1' width='100%'/>
17 </imageobject>
18 </mediaobject>
19
20 <title>
21 Toaster User Manual
22 </title>
23
24 <authorgroup>
25 <author>
26 <affiliation>
27 <orgname>&ORGNAME;</orgname>
28 </affiliation>
29 <email>&ORGEMAIL;</email>
30 </author>
31 </authorgroup>
32
33 <revhistory>
34 <revision>
35 <revnumber>1.8</revnumber>
36 <date>April 2015</date>
37 <revremark>The initial document released with the Yocto Project 1.8 Release.</revremark>
38 </revision>
39 <revision>
40 <revnumber>2.0</revnumber>
41 <date>October 2015</date>
42 <revremark>Released with the Yocto Project 2.0 Release.</revremark>
43 </revision>
44 <revision>
45 <revnumber>2.1</revnumber>
46 <date>April 2016</date>
47 <revremark>Released with the Yocto Project 2.1 Release.</revremark>
48 </revision>
49 <revision>
50 <revnumber>2.2</revnumber>
51 <date>October 2016</date>
52 <revremark>Released with the Yocto Project 2.2 Release.</revremark>
53 </revision>
54 <revision>
55 <revnumber>2.3</revnumber>
56 <date>May 2017</date>
57 <revremark>Released with the Yocto Project 2.3 Release.</revremark>
58 </revision>
59 <revision>
60 <revnumber>2.4</revnumber>
61 <date>October 2017</date>
62 <revremark>Released with the Yocto Project 2.4 Release.</revremark>
63 </revision>
64 <revision>
65 <revnumber>2.5</revnumber>
66 <date>May 2018</date>
67 <revremark>Released with the Yocto Project 2.5 Release.</revremark>
68 </revision>
69 <revision>
70 <revnumber>2.6</revnumber>
71 <date>November 2018</date>
72 <revremark>Released with the Yocto Project 2.6 Release.</revremark>
73 </revision>
74 <revision>
75 <revnumber>2.7</revnumber>
76 <date>May 2019</date>
77 <revremark>Released with the Yocto Project 2.7 Release.</revremark>
78 </revision>
79 <revision>
80 <revnumber>3.0</revnumber>
81 <date>October 2019</date>
82 <revremark>Released with the Yocto Project 3.0 Release.</revremark>
83 </revision>
84 <revision>
85 <revnumber>3.1</revnumber>
86 <date>&REL_MONTH_YEAR;</date>
87 <revremark>Released with the Yocto Project 3.1 Release.</revremark>
88 </revision>
89 </revhistory>
90
91 <copyright>
92 <year>&COPYRIGHT_YEAR;</year>
93 <holder>Linux Foundation</holder>
94 </copyright>
95
96 <legalnotice>
97 <para>
98 Permission is granted to copy, distribute and/or modify this document under
99 the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
100 </para>
101 <note><title>Manual Notes</title>
102 <itemizedlist>
103 <listitem><para>
104 This version of the
105 <emphasis>Toaster User Manual</emphasis>
106 is for the &YOCTO_DOC_VERSION; release of the
107 Yocto Project.
108 To be sure you have the latest version of the manual
109 for this release, go to the
110 <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink>
111 and select the manual from that site.
112 Manuals from the site are more up-to-date than manuals
113 derived from the Yocto Project released TAR files.
114 </para></listitem>
115 <listitem><para>
116 If you located this manual through a web search, the
117 version of the manual might not be the one you want
118 (e.g. the search might have returned a manual much
119 older than the Yocto Project version with which you
120 are working).
121 You can see all Yocto Project major releases by
122 visiting the
123 <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
124 page.
125 If you need a version of this manual for a different
126 Yocto Project release, visit the
127 <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink>
128 and select the manual set by using the
129 "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
130 pull-down menus.
131 </para></listitem>
132 <listitem>
133 <para>
134 To report any inaccuracies or problems with this
135 (or any other Yocto Project) manual, send an email to
136 the Yocto Project documentation mailing list at
137 <filename>docs@lists.yoctoproject.org</filename> or
138 log into the freenode <filename>#yocto</filename> channel.
139 </para>
140 </listitem>
141 </itemizedlist>
142 </note>
143
144 </legalnotice>
145
146 </bookinfo>
147
148 <xi:include href="toaster-manual-intro.xml"/>
149
150 <xi:include href="toaster-manual-start.xml"/>
151
152 <xi:include href="toaster-manual-setup-and-use.xml"/>
153
154 <xi:include href="toaster-manual-reference.xml"/>
155
156</book>
157<!--
158vim: expandtab tw=80 ts=4
159-->