summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2015-02-18 06:24:18 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2015-04-01 17:36:05 +0100
commit693ba0b14fa4aa166a072ab0080de666af239b03 (patch)
tree174284b3ab867f8c2169f682e247762d8ee90140 /documentation
parente7b07d33c2d7e1ef231a1d99183d00f3c0882218 (diff)
downloadpoky-693ba0b14fa4aa166a072ab0080de666af239b03.tar.gz
toaster-manual: Draft of Manual.
Fixes [YOCTO #6901] (From yocto-docs rev: 258b46b0f3e23045b5fb8c97d03dceb69db5ce20) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/template/embedded_video.xsl22
-rw-r--r--documentation/toaster-manual/figures/hosted-service.pngbin0 -> 13552 bytes
-rw-r--r--documentation/toaster-manual/figures/simple-configuration.pngbin0 -> 10789 bytes
-rw-r--r--documentation/toaster-manual/toaster-manual-customization.xsl4
-rw-r--r--documentation/toaster-manual/toaster-manual-intro.xml224
-rw-r--r--documentation/toaster-manual/toaster-manual-reference.xml1069
-rw-r--r--documentation/toaster-manual/toaster-manual-setup-and-use.xml920
-rw-r--r--documentation/toaster-manual/toaster-manual-start.xml137
-rw-r--r--documentation/toaster-manual/toaster-manual.xml2
9 files changed, 2084 insertions, 294 deletions
diff --git a/documentation/template/embedded_video.xsl b/documentation/template/embedded_video.xsl
new file mode 100644
index 0000000000..dfb33c3441
--- /dev/null
+++ b/documentation/template/embedded_video.xsl
@@ -0,0 +1,22 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<xsl:stylesheet version="1.0"
3 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
4 xmlns:d="http://docbook.org/ns/docbook">
5
6 <xsl:output method="html" />
7
8 <xsl:template match="/d:chapter/d:section/d:mediaobject">
9 <xsl:for-each select=".">
10 <xsl:variable name="vid_url">
11 <xsl:value-of select="./d:videoobject/d:videodata/@fileref" />
12 </xsl:variable>
13 <div style="text-align: center; margin: auto">
14 <object type="application/x-shockwave-flash" width="640" height="420" data="{$vid_url}?color2=FBE9EC&amp;showsearch=0&amp;version=3&amp;modestbranding=1&amp;fs=1">
15 <param name="movie" value="{$vid_url}?color2=FBE9EC&amp;showsearch=0&amp;version=3&amp;modestbranding=1&amp;fs=1" />
16 <param name="allowFullScreen" value="true" />
17 <param name="allowscriptaccess" value="always" />
18 </object>
19 </div>
20 </xsl:for-each>
21 </xsl:template>
22</xsl:stylesheet>
diff --git a/documentation/toaster-manual/figures/hosted-service.png b/documentation/toaster-manual/figures/hosted-service.png
new file mode 100644
index 0000000000..01fea7b245
--- /dev/null
+++ b/documentation/toaster-manual/figures/hosted-service.png
Binary files differ
diff --git a/documentation/toaster-manual/figures/simple-configuration.png b/documentation/toaster-manual/figures/simple-configuration.png
new file mode 100644
index 0000000000..e8fce2bf18
--- /dev/null
+++ b/documentation/toaster-manual/figures/simple-configuration.png
Binary files differ
diff --git a/documentation/toaster-manual/toaster-manual-customization.xsl b/documentation/toaster-manual/toaster-manual-customization.xsl
index e253aedd9a..29d29c452e 100644
--- a/documentation/toaster-manual/toaster-manual-customization.xsl
+++ b/documentation/toaster-manual/toaster-manual-customization.xsl
@@ -1,13 +1,15 @@
1<?xml version='1.0'?> 1<?xml version='1.0'?>
2<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"> 2<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">
3 3
4 <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" /> 4<!-- <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" /> -->
5 <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
5 6
6 <xsl:include href="../template/permalinks.xsl"/> 7 <xsl:include href="../template/permalinks.xsl"/>
7 <xsl:include href="../template/section.title.xsl"/> 8 <xsl:include href="../template/section.title.xsl"/>
8 <xsl:include href="../template/component.title.xsl"/> 9 <xsl:include href="../template/component.title.xsl"/>
9 <xsl:include href="../template/division.title.xsl"/> 10 <xsl:include href="../template/division.title.xsl"/>
10 <xsl:include href="../template/formal.object.heading.xsl"/> 11 <xsl:include href="../template/formal.object.heading.xsl"/>
12 <xsl:include href="../template/embedded_video.xsl"/>
11 13
12 <xsl:param name="html.stylesheet" select="'toaster-manual-style.css'" /> 14 <xsl:param name="html.stylesheet" select="'toaster-manual-style.css'" />
13 <xsl:param name="chapter.autolabel" select="1" /> 15 <xsl:param name="chapter.autolabel" select="1" />
diff --git a/documentation/toaster-manual/toaster-manual-intro.xml b/documentation/toaster-manual/toaster-manual-intro.xml
index 378f33420c..ad9e08b50d 100644
--- a/documentation/toaster-manual/toaster-manual-intro.xml
+++ b/documentation/toaster-manual/toaster-manual-intro.xml
@@ -6,95 +6,12 @@
6<title>Introduction</title> 6<title>Introduction</title>
7 7
8 <para> 8 <para>
9 Toaster is web interface to the OpenEmbedded build system, which uses 9 Toaster is a web interface to the Yocto Project's
10 BitBake. 10 <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.
11 The interface allows you to access a datastore that retains build 11 The interface enables you to configure and run your builds.
12 information and report out on the information. 12 Information about builds is collected and stored in a database.
13 </para> 13 You can use Toaster to configure and start builds on multiple
14<!--THE FOLLOWING IS DETAIL THAT I THINK BELEN WANTED OUT FOR THE MOMENT 14 remote build servers.
15 The interface is based on a Representational State Transfer
16 (REST) API that queries for and returns build information using
17 <filename>GET</filename> and <filename>JSON</filename>.
18 These types of search operations retrieve sets of objects from
19 a datastore used to collect build information.
20 The results contain all the data for the objects being returned.
21 You can order the results of the search by key and the search
22 parameters are consistent for all object types.
23 </para>
24-->
25
26 <para>
27 You can use Toaster in several different modes:
28 <itemizedlist>
29 <listitem><para><emphasis>Analysis Mode:</emphasis>
30 In this mode, you can record builds and statistics.
31 In Analysis Mode, you have direct access to the
32 <filename>bitbake</filename> command, which you use to build
33 images.</para>
34 <para>Analysis Mode requires you to have first started
35 Toaster and then to initiate your build using the
36 <filename>bitbake</filename> command from the shell.
37 Toaster must be started before the build or it will not
38 collect build data.
39 </para></listitem>
40 <listitem><para><emphasis>Build Mode:</emphasis>
41 In this mode, Toaster handles the build configuration GUI
42 (through project pages) and build scheduling and execution.
43 In this mode, all your interaction with the build system
44 happens through the web interface.
45 You do not have direct access to the
46 <filename>bitbake</filename> command.</para>
47 <para>Using this mode, you configure and start your builds
48 with Toaster's GUI.
49 Each configuration is a project, which requires version and
50 build system selection.
51 As shipped, Toaster supports the Yocto Project releases
52 1.8 and beyond.
53 Aside from these supported releases, you can also select
54 the "Local Yocto Project", which allows you to use your
55 local clone of the Yocto Project
56 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
57 (e.g. <filename>poky</filename>).</para>
58 <para>Build Mode also works two separate ways: locally and
59 remotely.
60 While you can use Build Mode locally, it is best to use
61 Toaster's Build Mode through a hosted service where it can
62 shared by multiple user.
63 </para></listitem>
64 </itemizedlist>
65 </para>
66
67 <para>
68 Using Toaster, you can do the following:
69 <note><title>REVIEWER NOTE</title>
70 Belen suggested we split this list out into things that
71 Analysis Mode and Build Mode can do.
72 Also, we can structure the lists so the Build Mode list
73 leverages off what is listed for Analysis Mode.
74 I do not know the information for the complete lists.
75 Someone needs to help me out here.
76 For now, I am leaving the list as follows and will need some
77 information.
78 </note>
79 <itemizedlist>
80 <listitem><para>
81 See information about the tasks executed
82 and reused during the build.
83 </para></listitem>
84 <listitem><para>
85 See what is built (recipes and
86 packages) and what packages were installed into the final
87 image.
88 </para></listitem>
89 <listitem><para>
90 See performance-related information such
91 as build time, CPU usage, and disk I/O.
92 </para></listitem>
93 <listitem><para>
94 Examine error, warning and trace messages
95 to aid in debugging.
96 </para></listitem>
97 </itemizedlist>
98 </para> 15 </para>
99 16
100 <note> 17 <note>
@@ -116,10 +33,131 @@
116 </para> 33 </para>
117 </note> 34 </note>
118 35
119 <para> 36 <section id='intro-modes'>
120 The remainder of this manual describes what you need to have in 37 <title>Toaster Operational Modes</title>
121 place to use Toaster, how to start it, use it, and stop it. 38
122 </para> 39 <para>
40 You can use Toaster in Analysis Mode or Build Mode:
41 <itemizedlist>
42 <listitem><para><emphasis>Analysis Mode:</emphasis>
43 In Analysis Mode, you can record builds and statistics.
44 In this Mode, you directly access the
45 <filename>bitbake</filename> command, which you then use to
46 build images.</para>
47 <para>Analysis Mode requires you to have first started
48 Toaster and then to initiate your build using the
49 <filename>bitbake</filename> command from the shell.
50 Toaster must be started before the build or it will not
51 collect build data.</para>
52 <para>Toaster has the following capabilities in
53 Analysis Mode:
54 <itemizedlist>
55 <listitem><para>
56 See what was built (recipes and packages) and what
57 packages were installed into your final image.
58 </para></listitem>
59 <listitem><para>
60 Browse the directory structure of your image.
61 </para></listitem>
62 <listitem><para>
63 See the value of all variables in your build
64 configuration, and which files set each value.
65 </para></listitem>
66 <listitem><para>
67 Examine error, warning and trace messages to aid
68 in debugging.
69 </para></listitem>
70 <listitem><para>
71 See information about the BitBake tasks executed
72 and reused during your build, including those that
73 used shared state.
74 </para></listitem>
75 <listitem><para>
76 See dependency relationships between recipes,
77 packages and tasks
78 </para></listitem>
79 <listitem><para>
80 See performance information such as build time,
81 task time, CPU usage, and disk I/O.
82 </para></listitem>
83 </itemizedlist>
84 </para></listitem>
85 <listitem><para><emphasis>Build Mode:</emphasis>
86 In Build Mode, Toaster handles the build configuration,
87 scheduling and execution.
88 In this mode, all your interaction with the build system
89 happens through the web interface.
90 You do not have direct access to the
91 <filename>bitbake</filename> command.</para>
92 <para>Using this mode, you configure and start your builds
93 within Toaster's GUI.
94 Each project can be configured for a specific version
95 of the build system.
96 As shipped, Toaster supports Yocto Project Releases 1.7 and
97 beyond.</para>
98 <para>Toaster has all the same capabilities in Build Mode
99 as it does in Analysis Mode plus the following:
100 <itemizedlist>
101 <listitem><para>
102 Browse layers listed in the various
103 <link linkend='layer-source'>layer sources</link>
104 that are available in your project (e.g. the
105 OpenEmbedded Metadata Index at
106 <ulink url='http://layers.openembedded.org/layerindex/'></ulink>).
107 </para></listitem>
108 <listitem><para>
109 Import your own layers for building.
110 </para></listitem>
111 <listitem><para>
112 Add and remove layers from your configuration.
113 </para></listitem>
114 <listitem><para>
115 Set configuration variables.
116 </para></listitem>
117 <listitem><para>
118 Select a target or multiple targets to build.
119 </para></listitem>
120 <listitem><para>
121 Start your builds.
122 </para></listitem>
123 </itemizedlist>
124 </para></listitem>
125 </itemizedlist>
126 </para>
127 </section>
128
129 <section id='toaster-installation-options'>
130 <title>Installation Options</title>
131
132 <para>
133 You can set Toaster up to run as a local instance or as a shared
134 hosted service.
135 Regardless of how you set up Toaster, both Analysis and Build
136 Modes are available.
137 </para>
138
139 <para>
140 When Toaster is set up as a local instance, all the components
141 reside on a single build host.
142 Fundamentally, a local instance of Toaster is suited for a single
143 user developing on a single build host.
144 </para>
145
146 <para>
147 <imagedata fileref="figures/simple-configuration.png" align="center" width="6in" depth="1.5in" />
148 </para>
149
150 <para>
151 Toaster as a hosted service is suited for multiple users
152 developing across several build hosts.
153 When Toaster is set up as a hosted service, its components can
154 be spread across several machines:
155 </para>
156
157 <para>
158 <imagedata fileref="figures/hosted-service.png" align="center" width="6in" depth="3.5in" />
159 </para>
160 </section>
123 161
124<!--THIS EXTRA INFORMATION PROBABLY WILL GO AWAY 162<!--THIS EXTRA INFORMATION PROBABLY WILL GO AWAY
125 For additional information on installing and running Toaster, see the 163 For additional information on installing and running Toaster, see the
diff --git a/documentation/toaster-manual/toaster-manual-reference.xml b/documentation/toaster-manual/toaster-manual-reference.xml
new file mode 100644
index 0000000000..05184fa1eb
--- /dev/null
+++ b/documentation/toaster-manual/toaster-manual-reference.xml
@@ -0,0 +1,1069 @@
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
5<chapter id='toaster-manual-reference'>
6
7<title>Concepts and Reference</title>
8
9 <para>
10 In order to configure and use Toaster, you should understand some
11 concepts and have some basic command reference material available.
12 This final chapter provides conceptual information on layer sources,
13 releases, and JSON configuration files.
14 Also provided is a quick look at some useful
15 <filename>manage.py</filename> commands.
16 Information on <filename>manage.py</filename> commands does exist
17 across the Web and the information in this manual by no means
18 attempts to provide a command reference.
19 However, having relevant command useful for the Toaster context
20 is helpful.
21 </para>
22
23 <section id='layer-source'>
24 <title>Layer Source</title>
25
26 <para>
27 In general, a layer source is some source of 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 Metadata 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_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
97 and
98 "<ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>Using the Yocto Project's BSP Tools</ulink>"
99 sections in the Yocto Project Board Support Package (BSP)
100 Developer's Guide.
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 </para>
138
139 <para>
140 The administration interface has a "Layer sources"
141 section that includes an "Add layer source" button.
142 Click that button and provide the required information.
143 Make sure you select "layerindex" as the layer source type.
144 </para>
145 </section>
146
147 <section id='select-the-toasterconf-json-file'>
148 <title>Select the <filename>toasterconf.json</filename> File</title>
149
150 <para>
151 If you do not want to use the Administration
152 Interface, you can edit the
153 <link linkend='toaster-json-files'><filename>toasterconf.json</filename></link>
154 file and reload it to Toaster.
155 </para>
156
157 <para>
158 When you set up Toaster in Build Mode, you are prompted to
159 select a Toaster configuration file.
160 This configuration file is used to set up the initial
161 configuration values within the Toaster database
162 including the layer sources.
163 Three versions of the configuration file exist:
164 <itemizedlist>
165 <listitem><para>
166 The first version of the file is found in the
167 <filename>conf</filename> directory of the
168 <filename>meta-yocto</filename> layer
169 (i.e.
170 <filename>meta-yocto/conf/toasterconf.json</filename>).
171 This version contains the default Yocto Project
172 configuration for Toaster.
173 You are prompted to select this file during the
174 Toaster set up process if you had cloned the
175 <filename>poky</filename> repository (i.e.
176 <filename>git://git.yoctoproject.org/poky</filename>).
177 </para></listitem>
178 <listitem><para>
179 The second version of the file is in the
180 <filename>conf</filename> directory of the
181 <filename>openembedded-core</filename> layer
182 (i.e. <filename>meta/conf/toasterconf.json</filename>).
183 This version contains the default OpenEmbedded
184 configuration for Toaster.
185 You are prompted to select this file during the
186 Toaster set up process if you had cloned the
187 <filename>openembedded-core</filename> repository
188 (i.e.
189 <filename>git://git.openembedded.org/openembedded-core</filename>).
190 </para></listitem>
191 <listitem><para>
192 The third version is a sample configuration
193 useful for when you want to set up a hosted
194 service in Build Mode.
195 You can find this version on the
196 <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>File:Toasterconf.json.txt.patch</ulink>
197 wiki page.
198 </para></listitem>
199 </itemizedlist>
200 </para>
201 </section>
202
203 <section id='edit-the-configuration-file'>
204 <title>Edit the Configuration File</title>
205
206 <para>
207 Edit the version of the
208 <filename>toasterconf.json</filename> file you
209 used to set up your Toaster instance.
210 In the file, you will find a section for layer sources
211 such as the following:
212 <literallayout class='monospaced'>
213 "layersources": [
214 {
215 "name": "Local Yocto Project",
216 "sourcetype": "local",
217 "apiurl": "../../",
218 "branches": ["HEAD", "master", "fido", "dizzy"],
219 "layers": [
220 {
221 "name": "openembedded-core",
222 "local_path": "meta",
223 "vcs_url": "remote:origin",
224 "dirpath": "meta"
225 },
226 {
227 "name": "meta-yocto",
228 "local_path": "meta-yocto",
229 "vcs_url": "remote:origin",
230 "dirpath": "meta-yocto"
231 },
232 {
233 "name": "meta-yocto-bsp",
234 "local_path": "meta-yocto-bsp",
235 "vcs_url": "remote:origin",
236 "dirpath": "meta-yocto-bsp"
237 }
238
239 ]
240 },
241 {
242 "name": "OpenEmbedded",
243 "sourcetype": "layerindex",
244 "apiurl": "http://layers.openembedded.org/layerindex/api/",
245 "branches": ["master", "fido", "dizzy"]
246 },
247 {
248 "name": "Imported layers",
249 "sourcetype": "imported",
250 "apiurl": "",
251 "branches": ["master", "fido", "dizzy", "HEAD"]
252
253 }
254 ],
255 </literallayout>
256 You should add your own layer source to this section by
257 following the same format used for the "OpenEmbedded"
258 layer source shown above.
259 </para>
260
261 <para>
262 Give your layer source a name, provide the URL of your
263 layer source API, use the source type "layerindex", and
264 indicate which branches from your layer source you want
265 to make available through Toaster.
266 For example, the OpenEmbedded layer source makes
267 available only its "master", "fido", and "dizzy"
268 branches.
269 </para>
270
271 <para>
272 The branches must match the branch you
273 set when configuring your releases.
274 For example, if you configure one release in Toaster
275 by setting its branch to "branch-one" and you configure
276 another release in Toaster by setting its branch to
277 "branch-two", the branches in your layer source should
278 be "branch-one" and "branch-two" as well.
279 Doing so creates a connection between the releases
280 and the layer information from your layer source.
281 Thus, when users create a project with a given
282 release, they will see the appropriate layers from
283 your layer source.
284 This connection ensures that only layers that are
285 compatible with the selected project release can be
286 selected for building.
287 </para>
288
289 <para>
290 Once you have added this information to the
291 <filename>toasterconf.json</filename> file, save your
292 changes.
293 </para>
294
295 <para>
296 In a terminal window, navigate to the directory that
297 contains the Toaster database, which by default is the
298 root of the Yocto Project
299 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
300 Once you are located in that directory, run the
301 "<filename>loadconf</filename>" command, which takes as
302 an argument the full path to the
303 <filename>toasterconf.json</filename> file you just edited.
304 For example, if you cloned the
305 <filename>poky</filename> repository and you edited the
306 <filename>meta-yocto/conf/toasterconf.json</filename> file,
307 you would type something like the following:
308 <literallayout class='monospaced'>
309 $ bitbake/lib/toaster/manage.py loadconf /home/scottrif/poky/meta-yocto/conf/toasterconf.json
310 </literallayout>
311 After entering this command, you need to update the
312 information from the layer index to populate the
313 Toaster database with the information from your layer
314 index.
315 To do that, you should run the
316 "<filename>lsupdates</filename>" command from the directory
317 that contains the Toaster database.
318 Here is an example:
319 <literallayout class='monospaced'>
320 $ bitbake/lib/toaster/manage.py lsupdates
321 </literallayout>
322 If Toaster can reach the API URL, you should see a message
323 telling you that Toaster is updating the layer source
324 information.
325 </para>
326
327 <para>
328 Once the information has been updated, verify the new layer
329 information is available by using the Toaster web interface.
330 To do that, visit the "All compatible layers" page inside a
331 Toaster project.
332 The layers from your layer index should be listed there.
333 </para>
334 </section>
335 </section>
336 </section>
337 </section>
338
339 <section id='toaster-releases'>
340 <title>Releases</title>
341
342 <para>
343 In the context of Toaster, the term "Release" refers to a set of
344 layers and a BitBake version the OpenEmbedded build system uses
345 to build something.
346 As shipped, Toaster is pre-configured with releases that
347 correspond to Yocto Project release branches.
348 However, you can modify, delete, and create new releases
349 according to your needs.
350 When you create a Toaster project using the web interface,
351 you are asked to choose a "Release."
352 This section provides some background information on releases.
353 </para>
354
355 <section id='toaster-releases-supported'>
356 <title>Pre-Configured Releases</title>
357
358 <para>
359 As shipped, Toaster is configured to use a specific set of
360 releases.
361 Of course, you can always configure Toaster to use any
362 release.
363 For example, you might want your project to build against a
364 specific commit of any of the "out-of-the-box" releases.
365 Or, you might want your project to build against different
366 revisions of OpenEmbedded and BitBake.
367 </para>
368
369 <para>
370 As shipped, Toaster is configured to work with the following
371 releases:
372 <itemizedlist>
373 <listitem><para><emphasis>Yocto Project 1.7 "Dizzy" or OpenEmbedded "Dizzy":</emphasis>
374 This release causes your Toaster projects to
375 build against the head of the dizzy branch at
376 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/?h=dizzy'></ulink>
377 or
378 <ulink url='http://git.openembedded.org/openembedded-core/commit/?h=dizzy'></ulink>.
379 </para></listitem>
380 <listitem><para><emphasis>Yocto Project 1.8 "Fido" or OpenEmbedded "Fido":</emphasis>
381 This release causes your Toaster projects to
382 build against the head of the fido branch at
383 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/?h=fido'></ulink>
384 or
385 <ulink url='http://git.openembedded.org/openembedded-core/commit/?h=fido'></ulink>.
386 </para></listitem>
387 <listitem><para><emphasis>Yocto Project "Master" or OpenEmbedded "Master":</emphasis>
388 This release causes your Toaster Projects to
389 build against the head of the master branch, which is
390 where active development takes place, at
391 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/'></ulink>
392 or
393 <ulink url='http://git.openembedded.org/openembedded-core/log/'></ulink>.
394 </para></listitem>
395 <listitem><para><emphasis>Local Yocto Project or Local OpenEmbedded:</emphasis>
396 This release causes your Toaster Projects to
397 build against the head of the <filename>poky</filename>
398 or <filename>openembedded-core</filename> clone you
399 have local to the machine running Toaster.
400 </para></listitem>
401 </itemizedlist>
402 </para>
403 </section>
404
405 <section id='toaster-releases-comprised-of'>
406 <title>What Makes Up a Release?</title>
407
408 <para>
409 A release consists of the following:
410 <itemizedlist>
411 <listitem><para><emphasis>Name:</emphasis>
412 The name of the release (<filename>name</filename>).
413 This release name never appears in the the Toaster
414 web interface.
415 Consequently, a user never sees the release name.
416 </para></listitem>
417 <listitem><para><emphasis>Description:</emphasis>
418 The textual description of the release
419 (<filename>description</filename>).
420 This description is what users encounter when creating
421 projects with the Toaster web interface.
422 When you configure your release, be sure to use
423 a description that sufficiently describes and is
424 understandable.
425 If Toaster has more than one release configured, the
426 release descriptions appear listed in a drop down menu
427 when a user creates a new project.
428 If Toaster has only one release configured, all
429 projects created using the web interface take that
430 release and the drop down menu does not display in the
431 Toaster web interface.
432 </para></listitem>
433 <listitem><para><emphasis>BitBake:</emphasis>
434 The Bitbake version (<filename>bitbake</filename>)
435 used to build layers set in the current release.
436 This version is described by a name, a Git URL, a
437 branch in the Git URL, and a directory path in the
438 Git repository.
439 As an example, consider the following snippet from
440 a Toaster JSON configuration file.
441 This BitBake version uses the master branch from the
442 OpenEmbedded repository:
443 <literallayout class='monospaced'>
444 "bitbake" : [
445 {
446 "name": "master",
447 "giturl": "git://git.openembedded.org/bitbake",
448 "branch": "master",
449 "dirpath": ""
450 }
451 ]
452 </literallayout>
453 Here is more detail on each of the items that comprise
454 the BitBake version:
455 <itemizedlist>
456 <listitem><para><emphasis>Name:</emphasis>
457 A string
458 (<filename>name</filename>) used to refer to
459 the version of BitBake you are using with
460 Toaster.
461 This name is never exposed through Toaster.
462 </para></listitem>
463 <listitem><para><emphasis>Git URL:</emphasis>
464 The URL <filename>giturl</filename>
465 for the BitBake Git repository cloned
466 for Toaster projects.
467 </para></listitem>
468 <listitem><para><emphasis>Branch:</emphasis>
469 The Git branch, or revision,
470 (<filename>branch</filename>) of the BitBake
471 repository used with Toaster.
472 </para></listitem>
473 <listitem><para><emphasis>Directory Path:</emphasis>
474 The sub-directory of the BitBake repository
475 (<filename>dirpath</filename>).
476 If the Git URL includes more than one
477 repository, you need to set this directory.
478 If the URL does not include more than a single
479 repository, you can set
480 <filename>dirpath</filename> to a null string
481 (i.e. "").
482 </para></listitem>
483 </itemizedlist>
484 </para></listitem>
485 <listitem><para><emphasis>Branch:</emphasis>
486 The branch for the layer source
487 (<filename>branch</filename>) used with the release.
488 For example, for the OpenEmbedded layer source, the
489 "master", "fido", and "dizzy" branches are available.
490 </para></listitem>
491 <listitem><para><emphasis>Default Layers:</emphasis>
492 The set of default layers
493 (<filename>defaultlayers</filename>) automatically
494 added to the project configuration when a project is
495 created.
496 You can download the recommended configuration
497 for this case from
498 <ulink url='&YOCTO_WIKI_URL;/wiki/File:Toasterconf.json.txt.patch'></ulink>.
499 </para></listitem>
500 <listitem><para><emphasis>Layer Source Priorities</emphasis>
501 A specification of
502 <link linkend='layer-source'>layer source</link>
503 priorities (<filename>layersourcepriority</filename>).
504 In order for Toaster to work as intended, the
505 "Imported layers" layer source should have the highest
506 priority, which means that layers manually imported by
507 users with the "Import layer" functionality will
508 always be visible and available for selection.
509 </para></listitem>
510 <listitem><para><emphasis>Help Text:</emphasis>
511 Help text (<filename>helptext</filename>) that explains
512 what the release does when selected.
513 This help text appears below the release drop-down
514 menu when you create a Toaster project.
515 The help text should assist users in making the correct
516 decision regarding the release to use for a given
517 project.
518 </para></listitem>
519 </itemizedlist>
520 </para>
521
522 <para>
523 To summarize what comprises a release, consider the following
524 example from a Toaster JSON file.
525 The configuration names the release "master" and sets it to
526 use the master branch of the
527 <filename>openembedded-core</filename> layer.
528 The BitBake version used would be defined as shown earlier
529 in the previous list:
530 <literallayout class='monospaced'>
531 "releases": [
532 {
533 "name": "master",
534 "description": "OpenEmbedded master",
535 "bitbake": "master",
536 "branch": "master",
537 "defaultlayers": [ "openembedded-core" ],
538 "layersourcepriority": { "Imported layers": 99, "Local OpenEmbedded" : 10, "OpenEmbedded" : 0 },
539 "helptext": "Toaster will run your builds using the OpenEmbedded master branch, where active development takes place. This is not a stable branch, so your builds might not work as expected."
540 }
541 ]
542 </literallayout>
543 </para>
544 </section>
545 </section>
546
547 <section id='toaster-json-files'>
548 <title>JSON Files</title>
549
550 <para>
551 If you are going to be using the Toaster in Build Mode, it must
552 be initially configured before use.
553 Configuration customizes layer source settings and Toaster defaults
554 for all users and is performed by the person responsible for
555 Toaster Configuration (i.e the Toaster Administrator).
556 The Toaster Administrator performs this configuration through the
557 admin web interface.
558 </para>
559
560 <para>
561 To make it easier to initially start Toaster, you can import a
562 pre-defined configuration file using the
563 <link linkend='toaster-command-loadconf'><filename>loadconf</filename></link>
564 command.
565 <note>
566 The configuration file is a JSON-formatted text file with
567 specific fields that Toaster recognizes.
568 It is not a data dump from the database, so it cannot be
569 loaded directly in the database.
570 </note>
571 </para>
572
573 <para>
574 By convention, the supplied configuration files are named
575 <filename>toasterconf.json</filename>.
576 The Toaster Administrator can customize the file prior to loading
577 it into Toaster.
578 In the Local Toaster Build Mode, the system startup script
579 actively looks for compatible configuration files and prompts
580 you to select a file to load if it detects that the database has
581 not been configured.
582 </para>
583
584 <section id='json-file-choices'>
585 <title>Configuration File Choices</title>
586
587 <para>
588 Three versions of the configuration file exist:
589 <itemizedlist>
590 <listitem><para>
591 The
592 <filename>meta-yocto/conf/toasterconf.json</filename>
593 in the <filename>conf</filename> directory of the
594 Yocto Project's <filename>meta-yocto</filename> layer.
595 This version contains the default Yocto Project
596 configuration for Toaster.
597 You are prompted to select this file during the Toaster
598 set up process if you cloned the
599 <filename>poky</filename> repository (i.e.
600 <filename>&YOCTO_GIT_URL;/poky</filename>).
601 </para></listitem>
602 <listitem><para>
603 The <filename>meta/conf/toasterconf.json</filename>
604 in the <filename>conf</filename> directory of the
605 OpenEmbedded's <filename>openembedded-core</filename>
606 layer.
607 This version contains the default OpenEmbedded
608 configuration for Toaster.
609 You are prompted to select this file during the Toaster
610 set up process if you had cloned the
611 <filename>openembedded-core</filename> repository (i.e.
612 <filename>git://git.openembedded.org/openembedded-core</filename>).
613 </para></listitem>
614 <listitem><para>
615 The <filename>Toasterconf.json.txt.patch</filename>
616 located on the
617 <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>File:Toasterconf.json.txt.patch</ulink>
618 wiki page.
619 This version of the file is useful as a sample
620 configuration for when you want to set up Toaster as a
621 hosted service in Build Mode.
622 </para></listitem>
623 </itemizedlist>
624 </para>
625 </section>
626
627 <section id='json-structure'>
628 <title>File Structure</title>
629
630 <para>
631 The <filename>toasterconf.json</filename> file consists of
632 easily readable areas: configuration, layer sources, BitBake,
633 default, and releases.
634 </para>
635
636 <section id='json-config-area'>
637 <title>Configuration Area</title>
638
639 <para>
640 This area of the JSON file sets which variables are exposed
641 to users through the Toaster web interface.
642 Users can easily edit these variables.
643 </para>
644
645 <para>
646 The variables you set here are displayed in the
647 "Configuration variables" page in Toaster.
648 Minimally, you should set the
649 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
650 variable, which appears to users as part of the project
651 page in Toaster.
652 </para>
653
654 <para>
655 Here is the default <filename>config</filename> area:
656 <literallayout class='monospaced'>
657 "config": {
658 "MACHINE" : "qemux86",
659 "DISTRO" : "poky",
660 "IMAGE_FSTYPES": "ext3 jffs2 tar.bz2",
661 "IMAGE_INSTALL_append": "",
662 "PACKAGE_CLASSES": "package_rpm",
663 "SDKMACHINE" : "x86_64"
664 },
665 </literallayout>
666 </para>
667 </section>
668
669 <section id='json-layersources-area'>
670 <title>Layer Sources Area</title>
671
672 <para>
673 This area of the JSON file defines the
674 <link linkend='layer-source'>layer sources</link>
675 Toaster uses.
676 Toaster reads layer information from layer sources.
677 Three types of layer sources exist that Toaster
678 recognizes: Local, LayerIndex, and Imported.
679 </para>
680
681 <para>
682 The Local layer source reads layers from Git clones
683 available on your local drive.
684 Using a local layer source enables you to easily test
685 Toaster.
686 <note>
687 If you are setting up a hosted version of Toaster,
688 it does not make sense to have a local layer source.
689 </note>
690 </para>
691
692 <para>
693 The LayerIndex layer source uses a REST API exposed by
694 instances of the Layer Index application (e.g the public
695 <ulink url='http://layers.openembedded.org/'></ulink>)
696 to read layer data.
697 </para>
698
699 <para>
700 The Imported layer source is reserved for layer data
701 manually introduced by the user or Toaster Administrator
702 through the GUI.
703 This layer source lets users import their own layers
704 and build them with Toaster.
705 You should not remove the imported layer source.
706 </para>
707
708 <para>
709 Here is the default <filename>layersources</filename> area:
710 <literallayout class='monospaced'>
711 "layersources": [
712 {
713 "name": "Local Yocto Project",
714 "sourcetype": "local",
715 "apiurl": "../../",
716 "branches": ["HEAD", "master", "fido", "dizzy"],
717 "layers": [
718 {
719 "name": "openembedded-core",
720 "local_path": "meta",
721 "vcs_url": "remote:origin",
722 "dirpath": "meta"
723 },
724 {
725 "name": "meta-yocto",
726 "local_path": "meta-yocto",
727 "vcs_url": "remote:origin",
728 "dirpath": "meta-yocto"
729 },
730 {
731 "name": "meta-yocto-bsp",
732 "local_path": "meta-yocto-bsp",
733 "vcs_url": "remote:origin",
734 "dirpath": "meta-yocto-bsp"
735 }
736
737 ]
738 },
739 {
740 "name": "OpenEmbedded",
741 "sourcetype": "layerindex",
742 "apiurl": "http://layers.openembedded.org/layerindex/api/",
743 "branches": ["master", "fido", "dizzy"]
744 },
745 {
746 "name": "Imported layers",
747 "sourcetype": "imported",
748 "apiurl": "",
749 "branches": ["master", "fido", "dizzy", "HEAD"]
750
751 }
752 ],
753 </literallayout>
754 </para>
755 </section>
756
757 <section id='json-bitbake-area'>
758 <title>BitBake Area</title>
759
760 <para>
761 This area of the JSON file defines the version of
762 BitBake Toaster uses.
763 As shipped, Toaster is configured to recognize three
764 versions of BitBake: master, dizzy, and HEAD.
765 </para>
766
767 <para>
768 Here is the default <filename>bitbake</filename> area:
769 <literallayout class='monospaced'>
770 "bitbake" : [
771 {
772 "name": "master",
773 "giturl": "remote:origin",
774 "branch": "master",
775 "dirpath": "bitbake"
776 },
777 {
778 "name": "fido",
779 "giturl": "remote:origin",
780 "branch": "fido",
781 "dirpath": "bitbake"
782 },
783 {
784 "name": "dizzy",
785 "giturl": "remote:origin",
786 "branch": "dizzy",
787 "dirpath": "bitbake"
788 },
789 {
790 "name": "HEAD",
791 "giturl": "remote:origin",
792 "branch": "HEAD",
793 "dirpath": "bitbake"
794 }
795 ],
796 </literallayout>
797 </para>
798 </section>
799
800 <section id='json-default-area'>
801 <title>Default Area</title>
802
803 <para>
804 This area of the JSON file establishes a default
805 release used by Toaster.
806 As shipped, Toaster uses the "master" release.
807 </para>
808
809 <para>
810 Here is the statement in the JSON file that establishes
811 the default release:
812 <literallayout class='monospaced'>
813 "defaultrelease": "master",
814 </literallayout>
815 </para>
816 </section>
817
818 <section id='json-releases-area'>
819 <title>Releases Area</title>
820
821 <para>
822 This area of the JSON file defines the versions of the
823 OpenEmbedded build system Toaster recognizes.
824 As shipped, Toaster is configured to work with the four
825 releases described in the
826 "<link linkend='toaster-releases-supported'>Pre-Configured Releases</link>"
827 section.
828 </para>
829
830 <para>
831 Here is the default <filename>releases</filename> area:
832 <literallayout class='monospaced'>
833 "releases": [
834 {
835 "name": "master",
836 "description": "Yocto Project master",
837 "bitbake": "master",
838 "branch": "master",
839 "defaultlayers": [ "openembedded-core", "meta-yocto", "meta-yocto-bsp"],
840 "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 },
841 "helptext": "Toaster will run your builds using the tip of the &lt;a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/\"&gt;Yocto Project master branch&lt;/a&gt;, where active development takes place. This is not a stable branch, so your builds might not work as expected."
842 },
843 {
844 "name": "fido",
845 "description": "Yocto Project 1.8 Fido",
846 "bitbake": "fido",
847 "branch": "fido",
848 "defaultlayers": [ "openembedded-core", "meta-yocto", "meta-yocto-bsp"],
849 "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 },
850 "helptext": "Toaster will run your builds with the tip of the &lt;a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=fido\"&gt;Yocto Project 1.8 \"Fido\"&lt;/a&gt; branch."
851 },
852 {
853 "name": "dizzy",
854 "description": "Yocto Project 1.7 Dizzy",
855 "bitbake": "dizzy",
856 "branch": "dizzy",
857 "defaultlayers": [ "openembedded-core", "meta-yocto", "meta-yocto-bsp"],
858 "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 },
859 "helptext": "Toaster will run your builds with the tip of the &lt;a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=dizzy\"&gt;Yocto Project 1.7 \"Dizzy\"&lt;/a&gt; branch."
860 },
861 {
862 "name": "local",
863 "description": "Local Yocto Project",
864 "bitbake": "HEAD",
865 "branch": "HEAD",
866 "defaultlayers": [ "openembedded-core", "meta-yocto", "meta-yocto-bsp"],
867 "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 },
868 "helptext": "Toaster will run your builds with the version of the Yocto Project you have cloned or downloaded to your computer."
869 }
870 ]
871 </literallayout>
872 </para>
873 </section>
874 </section>
875 </section>
876
877 <section id='toaster-useful-commands'>
878 <title>Useful Commands</title>
879
880 <para>
881 In addition to the web user interface and the scripts that start
882 and stop Toaster, command-line commands exist through the
883 <filename>manage.py</filename> management script.
884 You can find general documentation on
885 <filename>manage.py</filename> at the
886 <ulink url='https://docs.djangoproject.com/en/1.7/topics/settings/'>Django</ulink>
887 site.
888 However, several <filename>manage.py</filename> commands have been
889 created that are specific to Toaster and are used to control
890 configuration and back-end tasks.
891 You can locate these commands in the
892 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
893 (e.g. <filename>poky</filename>) at
894 <filename>bitbake/lib/manage.py</filename>.
895 This section documents those commands.
896 <note>
897 <para>
898 When using <filename>manage.py</filename> commands given
899 a default configuration, you must be sure that your
900 working directory is set to the
901 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
902 Using <filename>manage.py</filename> commands from the
903 Build Directory allows Toaster to find the
904 <filename>toaster.sqlite</filename> file, which is located
905 in the Build Directory.
906 </para>
907
908 <para>
909 For non-default database configurations, it is possible
910 that you can use <filename>manage.py</filename> commands
911 from a directory other than the Build directory.
912 To do so, the
913 <filename>toastermain/settings.py</filename> file must be
914 configured to point to the correct database backend.
915 </para>
916 </note>
917 </para>
918
919 <section id='toaster-command-buildslist'>
920 <title><filename>buildslist</filename></title>
921
922 <para>
923 The <filename>buildslist</filename> command lists all builds
924 that Toaster has recorded.
925 Access the command as follows:
926 <literallayout class='monospaced'>
927 $ bitbake/lib/toaster/manage.py buildslist
928 </literallayout>
929 The command returns a list, which includes numeric
930 identifications, of the builds that Toaster has recorded in the
931 current database.
932 </para>
933
934 <para>
935 You need to run the <filename>buildslist</filename> command
936 first to identify existing builds in the database before
937 using the
938 <link linkend='toaster-command-builddelete'><filename>builddelete</filename></link>
939 command.
940 For example, assuming default repository and build directory
941 names, the following two commands put you in the
942 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
943 and then return a list of the current builds, which would
944 be one in this case:
945 <literallayout class='monospaced'>
946 $ cd $HOME/poky/build
947 $ python ../bitbake/lib/toaster/manage.py buildslist
948 1: qemux86 poky core-image-minimal
949 </literallayout>
950 </para>
951 </section>
952
953 <section id='toaster-command-builddelete'>
954 <title><filename>builddelete</filename></title>
955
956 <para>
957 The <filename>builddelete</filename> command deletes data
958 associated with a build.
959 Access the command as follows:
960 <literallayout class='monospaced'>
961 $ bitbake/lib/toaster/manage.py builddelete <replaceable>build_id</replaceable>
962 </literallayout>
963 The command deletes all the build data for the specified
964 <replaceable>build_id</replaceable>.
965 This command is useful for removing old and unused data from
966 the database.
967 </para>
968
969 <para>
970 Prior to running the <filename>builddelete</filename>
971 command, you need to get the ID associated with builds
972 by using the
973 <link linkend='toaster-command-buildslist'><filename>buildslist</filename></link>
974 command.
975 </para>
976 </section>
977
978 <section id='toaster-command-perf'>
979 <title><filename>perf</filename></title>
980
981 <para>
982 The <filename>perf</filename> command measures Toaster
983 performance.
984 Access the command as follows:
985 <literallayout class='monospaced'>
986 $ bitbake/lib/toaster/manage.py perf
987 </literallayout>
988 The command is a sanity check that returns page loading
989 times in order to identify performance problems.
990 </para>
991 </section>
992
993 <section id='toaster-command-checksettings'>
994 <title><filename>checksettings</filename></title>
995
996 <para>
997 The <filename>checksettings</filename> command verifies
998 existing Toaster settings.
999 Access the command as follows:
1000 <literallayout class='monospaced'>
1001 $ bitbake/lib/toaster/manage.py checksettings
1002 </literallayout>
1003 In Managed Mode, Toaster uses settings that are based on the
1004 database to configure the building tasks.
1005 The <filename>checksettings</filename> command verifies that
1006 the database settings are valid in the sense that they have
1007 the minimal information needed to start a build.
1008 </para>
1009
1010 <para>
1011 In order for the <filename>checksettings</filename> command
1012 to work, the database must be correctly set up and not have
1013 existing data.
1014 To be sure the database is ready, you can run the following:
1015 <literallayout class='monospaced'>
1016 $ bitbake/lib/toaster/mana​ge.py syncdb
1017 $ bitbake/lib/toaster/mana​ge.py migrate orm
1018 $ bitbake/lib/toaster/mana​ge.py migrate bldcontrol
1019 </literallayout>
1020 After running these commands, you can run the
1021 <filename>checksettings</filename> command.
1022 </para>
1023 </section>
1024
1025 <section id='toaster-command-loadconf'>
1026 <title><filename>loadconf</filename></title>
1027
1028 <para>
1029 The <filename>loadconf</filename> command loads a Toaster
1030 configuration file (JSON file).
1031 You must run this on a new database that does not have any
1032 data.
1033 Running this command on an existing database that has data
1034 results in errors.
1035 Access the command as follows:
1036 <literallayout class='monospaced'>
1037 $ bitbake/lib/toaster/manage.py loadconf <replaceable>filepath</replaceable>
1038 </literallayout>
1039 The <filename>loadconf</filename> command configures a database
1040 based on the supplied <filename>toasterconf.json</filename>
1041 file.
1042 For information on the <filename>toasterconf.json</filename>,
1043 see the
1044 "<link linkend='toaster-json-files'>JSON Files</link>"
1045 section.
1046 </para>
1047 </section>
1048
1049 <section id='toaster-command-runbuilds'>
1050 <title><filename>runbuilds</filename></title>
1051
1052 <para>
1053 The <filename>runbuilds</filename> command launched
1054 scheduled builds.
1055 Access the command as follows:
1056 <literallayout class='monospaced'>
1057 $ bitbake/lib/toaster/manage.py runbuilds
1058 </literallayout>
1059 The <filename>runbuilds</filename> command checks if
1060 scheduled builds exist in the database and then launches them
1061 per schedule.
1062 The command returns after the builds start but before they
1063 complete.
1064 The "toasterui" build recorded updates the database when the
1065 builds complete.
1066 </para>
1067 </section>
1068 </section>
1069</chapter>
diff --git a/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
index f56d67ed37..b148d4f405 100644
--- a/documentation/toaster-manual/toaster-manual-setup-and-use.xml
+++ b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
@@ -6,12 +6,6 @@
6 6
7<title>Setting Up and Using Toaster</title> 7<title>Setting Up and Using Toaster</title>
8 8
9 <para>
10 You can set up Toaster as a local instance or as a hosted service.
11 Furthermore, you can use Toaster in Analysis Mode or Build Mode
12 from both set ups.
13 </para>
14
15 <section id='using-toaster-in-analysis-mode'> 9 <section id='using-toaster-in-analysis-mode'>
16 <title>Using Toaster in Analysis Mode</title> 10 <title>Using Toaster in Analysis Mode</title>
17 11
@@ -41,19 +35,14 @@
41 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" 35 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>"
42 section in the Yocto Project Quick Start for information. 36 section in the Yocto Project Quick Start for information.
43 </para></listitem> 37 </para></listitem>
44 <listitem><para><emphasis>Be Sure Ports are Free:</emphasis>
45 Make sure that port 8000 and 8200 are free.
46 In other words, make sure the ports do not have servers
47 on them.
48 </para></listitem>
49 <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis> 38 <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis>
50 From your 39 From your
51 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> 40 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
52 (e.g. <filename>poky/build</filename>), source the build 41 (e.g. <filename>poky/build</filename>), source the build
53 environment setup script (i.e. 42 environment setup script
54 <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink> 43 <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink>
55 or 44 or
56 <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>). 45 <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>.
57 </para></listitem> 46 </para></listitem>
58 <listitem><para><emphasis>Start Toaster:</emphasis> 47 <listitem><para><emphasis>Start Toaster:</emphasis>
59 From the 48 From the
@@ -72,13 +61,20 @@
72 $ bitbake core-image-minimal 61 $ bitbake core-image-minimal
73 </literallayout> 62 </literallayout>
74 </para></listitem> 63 </para></listitem>
64 <listitem><para><emphasis>Open Your Browser:</emphasis>
65 Open your browser and visit
66 <filename>http://host:port/toastergui</filename>.
67 For host and port values, see the output of the
68 <filename>source toaster start</filename> command.
69 For information on how to use Toaster, see the
70 "<link linkend='using-the-toaster-web-interface'>Using the Toaster Web Interface</link>"
71 section.
72 </para></listitem>
75 </orderedlist> 73 </orderedlist>
76 </para> 74 </para>
77 75
78 <para> 76 <para>
79 For information on how to use Toaster, see the 77
80 "<link linkend='using-the-toaster-interface'>Using the Toaster Interface</link>"
81 section.
82 </para> 78 </para>
83 </section> 79 </section>
84 80
@@ -86,68 +82,45 @@
86 <title>Setting Up a Hosted Service and Running in Analysis Mode</title> 82 <title>Setting Up a Hosted Service and Running in Analysis Mode</title>
87 83
88 <para> 84 <para>
89 A hosted service resides on a server and allows 85 A hosted service resides on a shared server and allows
90 multiple users to take advantage of Toaster. 86 multiple users to take advantage of Toaster.
91 In a production environment, you might want to have multiple
92 local instances of Toaster, which run on various remote
93 build machines, and have those local instances access and use
94 a single hosted Toaster service.
95 </para> 87 </para>
96 88
97 <para> 89 <para>
98 Starting Toaster with the <filename>toaster</filename> command 90 In a production environment, you might want to have multiple
99 (i.e. the script), causes three things to start: 91 local instances of the Toaster Logging Interface running on
92 various remote build machines, and have those local instances
93 access and use a single web server.
94 To do this, you need to do the following:
100 <itemizedlist> 95 <itemizedlist>
101 <listitem><para> 96 <listitem><para>
102 The BitBake server. 97 Maintain a common SQL database.
103 </para></listitem>
104 <listitem><para>
105 The Toaster User Interface, which connects to the
106 BitBake server on one side and to the SQL
107 database on the other side.
108 </para></listitem> 98 </para></listitem>
109 <listitem><para> 99 <listitem><para>
110 The web server, which reads the database and displays 100 Set up separate instances of BitBake servers
111 the web user interface. 101 and Toaster Logging Interfaces for each of those
102 separate BitBake servers.
112 </para></listitem> 103 </para></listitem>
113 </itemizedlist> 104 </itemizedlist>
114 Rather than starting Toaster with the script, you can set up
115 and start multiple instances of Toaster by manually starting
116 as many or few of these three components across your
117 environment.
118 This is possible because it is not required that Toaster starts
119 all three of its separate components in order to run.
120 Minimally, a local instance of Toaster requires just one of the
121 components.
122 </para> 105 </para>
123 106
124 <para> 107 <para>
125 The concepts for setting up multiple local instances of 108 The common SQL database allows the Web server to show data from
126 Toaster that share a single hosted service revolve
127 around maintaining a common SQL database and Web server that
128 shows data from that common database as well as setting up
129 separate local instances of BitBake servers and Toaster user
130 interfaces for each of those separate BitBake build
131 directories.
132 </para>
133
134 <para>
135 The common SQL database and the Web server show data from
136 all the various BitBake builds. 109 all the various BitBake builds.
137 Setting the SQL database outside of any 110 Setting the SQL database outside of any
138 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> 111 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
139 maintains a separation layer between the various local builds 112 maintains a separation between the various builds.
140 and the common database. 113 The BitBake servers, the SQL server, and the Web server or
141 The database is persistent because the logging database is set 114 servers can be run on separate machines.
142 up external to the BitBake database server (e.g. MySQL).
143 It is not even necessary to run the BitBake servers, the SQL
144 server, and the Web server on the same machine.
145 Each component can be run on its own machine.
146 </para> 115 </para>
147 116
148 <para> 117 <para>
149 Follow these steps to set up and run a hosted service and run 118 Follow these steps to set up and run a hosted service and run
150 Toaster in Analysis Mode: 119 Toaster in Analysis Mode:
120 <note>
121 The steps assume a Toaster installation path of
122 <filename>/opt/bitbake/</filename>.
123 </note>
151 <orderedlist> 124 <orderedlist>
152 <listitem><para><emphasis>Prepare your Build System:</emphasis> 125 <listitem><para><emphasis>Prepare your Build System:</emphasis>
153 Be sure your system has the Toaster requirements 126 Be sure your system has the Toaster requirements
@@ -162,71 +135,153 @@
162 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" 135 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>"
163 section in the Yocto Project Quick Start for information. 136 section in the Yocto Project Quick Start for information.
164 </para></listitem> 137 </para></listitem>
165 <listitem><para><emphasis>Be Sure Ports are Free:</emphasis> 138 <listitem><para><emphasis>Install and Set up the Database Server:</emphasis>
166 Make sure that port 8000 and 8200 are free. 139 You can use any SQL server out of the box.
167 In other words, make sure the ports do not have servers 140 It is recommended that you use
168 on them. 141 <filename>mysql-server</filename> because it has
169 </para></listitem> 142 the advantages of advanced SQL features along with a
170 <listitem><para><emphasis>Set up the SQL Logging Server and the Web Server:</emphasis> 143 fast and reliable database.
171 You can use any SQL server out of the box (e.g. 144 However, setting up <filename>mysql-server</filename>
172 <filename>mysgl-server</filename> for an Ubuntu build 145 is more complex and might require a Database
173 system). 146 Administrator to tune it.</para>
174 <note> 147 <para>Another supported database backend is
175 If you are concerned about performance, you might 148 <filename>sqlite3</filename>.
176 want to hand-tune the server. 149 With <filename>sqlite3</filename>, you have the
177 </note> 150 advantage of no configuration and an easy installation.
178 You must set up proper username and password access on 151 However, Toaster still requires direct access to the
179 the shared server for everyone that will be using 152 backend.
180 Toaster. 153 The <filename>sqlite</filename> backend is also slower
181 You need administration rights for the 154 as compared to <filename>mysql-server</filename>, and
182 <filename>mysql</filename> root account, which is not 155 has no transactional support.</para>
183 the same thing as root access on the machine.</para> 156 <para>You should set up proper username and password
184 <para>Clone a separate, local Git repository of the 157 access on the shared database for everyone that will
185 Toaster master branch to use for running the Web 158 be using Toaster.
186 server. 159 You need administrator rights for the root account,
187 The Git repository for Toaster is part of the 160 which is not the same thing as root access on the
188 Yocto Project 161 machine.
189 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. 162 Here is an example that installs
190 Consequently, you just need to set up a separate 163 <filename>mysql-server</filename> and sets up
191 local clone of the Yocto Project Source Directory 164 some user accounts and the database.
192 (e.g. <filename>poky</filename>): 165 <literallayout class='monospaced'>
166 $ apt-get install mysql-server
167 $ mysql -u root
168 mysql> CREATE USER 'newuser'@'localhost' IDENTIFIED BY 'password';
169 mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost';
170 mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost';
171 mysql> CREATE DATABASE 'toaster';
172 </literallayout>
173 You need a separate clone of the
174 <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>
175 for the Database Server.
176 This clone is only used for getting the latest Toaster
177 files.
178 You can set this up using the following Git command.
179 Be sure to set up the directory outside of any
180 Build Directories.
193 <literallayout class='monospaced'> 181 <literallayout class='monospaced'>
194 $ git clone git://git.yoctoproject.org/poky 182 $ git clone git://git.yoctoproject.org/poky
195 </literallayout> 183 </literallayout>
196 You do not perform builds on this tree. 184 In the separately cloned tree for the Database Server,
197 You need to create this local repository away from any
198 build areas.</para>
199 <para>In the separately cloned tree for the Web server,
200 edit the 185 edit the
201 <filename>bitbake/lib/toaster/toastermain/settings.py</filename> 186 <filename>bitbake/lib/toaster/toastermain/settings.py</filename>
202 file so that the <filename>DATABASES</filename> value 187 file so that the <filename>DATABASES</filename> value
203 points to the previously created database server. 188 points to the previously created database server.
204 Use the username and password established 189 Use the username and password established
205 earlier.</para> 190 earlier.
206 <para>Run the database sync scripts to create the 191 Here is an example:
207 needed tables as follows: 192 <literallayout class='monospaced'>
193 $ cat /opt/bitbake/lib/toaster/toastermain/settings.py
194 ...
195 DATABASES = {
196 'default': {
197 'ENGINE': 'django.db.backends.mysql',
198 'NAME': 'toaster',
199 'USER': 'newuser',
200 'PASSWORD': 'password',
201 'HOST': '192.168.0.25',
202 'PORT': '3306',
203 }
204 ...
205 </literallayout>
206 </para></listitem>
207 <listitem><para><emphasis>Install and Set Up the Web Server:</emphasis>
208 For a production environment, it is recommended that
209 you install and set up a front-end web server.
210 This server allows for load balancing and
211 multi-threading over Toaster and
212 <filename>django</filename> WSGI.
213 Here is an example that uses Apache web server.
214 <literallayout class='monospaced'>
215 $ apt-get install apache2 libapache2-mod-wsgi
216 $ a2enmod wsgi
217 $ cat /etc/apache2/sites-available/000-default.conf
218
219 ...
220
221 # the WSGIPythonPath is global
222 WSGIPythonPath /opt/bitbake/lib/toaster/
223
224 ...
225
226 #snip - in VirtualHost
227 WSGIScriptAlias / /opt/bitbake/lib/toaster/toastermain/wsgi.py
228
229 &lt;Directory //opt/bitbake/lib/toaster/toastermain/&gt;
230 &lt;Files wsgi.py&gt;
231 Require all granted
232 &lt;/Files&gt;
233 &lt;/Directory&gt;
234
235 ...
236 </literallayout>
237 You need to collect static media from Toaster and
238 continue configuring Apache to serve that static
239 media:
208 <literallayout class='monospaced'> 240 <literallayout class='monospaced'>
209 $ python bitbake/lib/toaster/manage.py syncdb 241 $ mkdir /var/www.html/static &amp;&amp; cd /var/www.html/static
210 $ python bitbake/lib/toaster/manage.py migrate orm 242 $ /opt/bitbake/lib/toaster/manage.py collectstatic
243 $ cat /etc/apache2/sites-available/000-default.conf
244
245 ...
246
247 # in VirtualHost, AHEAD of the WSGIScriptAlias definition
248 Alias /static/ /var/www.html/static/
249
250 &lt;Directory /var/www.html/static/&gt;
251 Require all granted
252 &lt;/Directory&gt;
253
254 ...
255
256 WSGIScript Alias / /opt/bitbake/lib/toaster/toastermain/wsgi.py
257
258 ...
211 </literallayout> 259 </literallayout>
212 You can start the Web server in the foreground or the 260 </para></listitem>
213 background using these commands, respectively: 261 <listitem><para><emphasis>Start Toaster:</emphasis>
262 Synchronize the databases for toaster, and then start
263 up the web server.
264 Here is an example that continues with the assumed
265 components from the previous steps:
214 <literallayout class='monospaced'> 266 <literallayout class='monospaced'>
215 $ python bitbake/lib/toaster/manage.py runserver 267 $ /opt/bitbake/lib/toaster/manage.py syncdb
216 $ nohup python bitbake/lib/toaster/manage.py runserver 2>toaster_web.log >toaster_web.log &amp; 268 $ /opt/bitbake/lib/toaster/manage.py migrate orm
269 $ /opt/bitbake/lib/toaster/manage.py migrate bldcontrol
270
271 $ service apache2 restart
217 </literallayout> 272 </literallayout>
273 You can find general documentation on
274 <filename>manage.py</filename> at the
275 <ulink url='https://docs.djangoproject.com/en/1.7/ref/django-admin/'>Django</ulink>
276 site.
277 For reference information on Toaster-specific
278 <filename>manage.py</filename> commands,
279 see the
280 "<link linkend='toaster-useful-commands'>Useful Commands</link>"
281 section.
218 </para></listitem> 282 </para></listitem>
219 <listitem><para><emphasis>Enable Build Logging to the Common SQL Server for Each Build Directory you are Using:</emphasis> 283 <listitem><para><emphasis>Enable Build Logging to the Common SQL Server for Each Build Directory you are Using:</emphasis>
220 For each build system that will be using Toaster and 284 In the Build Directory, create the required
221 the shared SQL server, you need to edit the
222 <filename>bitbake/lib/toaster/toastermain/settings.py</filename>
223 file to alter the <filename>DATABASES</filename> value
224 so that it points to the common SQL logging server.
225 <note><title>REVIEWER NOTE</title>
226 I don't see how to do this from the Wiki.
227 I need more clarification.
228 </note></para>
229 <para>In the Build Directory, create the required
230 <filename>conf/toaster.conf</filename> file as 285 <filename>conf/toaster.conf</filename> file as
231 described in 286 described in
232 <ulink url='https://wiki.yoctoproject.org/wiki/Setting_up_a_local_instance_of_Toaster'>BitBake Extra Options</ulink>. 287 <ulink url='https://wiki.yoctoproject.org/wiki/Setting_up_a_local_instance_of_Toaster'>BitBake Extra Options</ulink>.
@@ -240,24 +295,16 @@
240 INHERIT += "buildhistory" 295 INHERIT += "buildhistory"
241 BUILDHISTORY_COMMIT = "1" 296 BUILDHISTORY_COMMIT = "1"
242 </literallayout> 297 </literallayout>
243 Start the BitBake server using the following command: 298 You also need to point to the database.
299 You can do this by exporting the
300 <filename>DATABASE_URL</filename> variable as follows:
244 <literallayout class='monospaced'> 301 <literallayout class='monospaced'>
245 $ bitbake &dash;&dash;postread conf/toaster.conf &dash;&dash;server-only -t xmlrpc -B localhost:0 &amp;&amp; export BBSERVER=localhost:-1 302 export DATABASE_URL=mysql://<replaceable>newuser</replaceable>:<replaceable>password</replaceable>@192.168.0.25:3306/toaster
246 </literallayout> 303 </literallayout>
247 Start the logging user interface using the following
248 command:
249 <literallayout class='monospaced'>
250 $ nohup bitbake &dash;&dash;observe-only -u toasterui >toaster_ui.log &amp;
251 </literallayout>
252 <note>
253 No hard-coded ports are used as there is enough code
254 to run <filename>autodiscovery</filename>
255 for ports to prevent collisions.
256 </note>
257 </para></listitem> 304 </para></listitem>
258 <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis> 305 <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis>
259 From your 306 From your
260 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> 307 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
261 on each of the build systems, 308 on each of the build systems,
262 (e.g. <filename>poky/build</filename>), source the 309 (e.g. <filename>poky/build</filename>), source the
263 build environment setup script (i.e. 310 build environment setup script (i.e.
@@ -265,6 +312,26 @@
265 or 312 or
266 <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>). 313 <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>).
267 </para></listitem> 314 </para></listitem>
315 <listitem><para><emphasis>Start the BitBake Server:</emphasis>
316 Start the BitBake server using the following command:
317 <literallayout class='monospaced'>
318 $ bitbake --postread conf/toaster.conf --server-only -t xmlrpc -B localhost:0 &amp;&amp; export BBSERVER=localhost:-1
319 </literallayout>
320 </para></listitem>
321 <listitem><para><emphasis>Start the Logging Server:</emphasis>
322 Start the Toaster Logging Interface using the following
323 command:
324 <literallayout class='monospaced'>
325 $ nohup bitbake --observe-only -u toasterui >toaster_ui.log &amp;
326 </literallayout>
327 <note>
328 No hard-coded ports are used in the BitBake options
329 as there is enough code to run
330 <filename>autodiscovery</filename> for BitBake
331 ports.
332 Doing so prevents collisions.
333 </note>
334 </para></listitem>
268 <listitem><para><emphasis>Start Builds Using BitBake:</emphasis> 335 <listitem><para><emphasis>Start Builds Using BitBake:</emphasis>
269 Use the <filename>bitbake</filename> command to start a 336 Use the <filename>bitbake</filename> command to start a
270 build on a build system. 337 build on a build system.
@@ -284,8 +351,9 @@
284 </para> 351 </para>
285 352
286 <para> 353 <para>
287 For information on how to use Toaster, see the 354 For information on how to use the Toaster web interface,
288 "<link linkend='using-the-toaster-interface'>Using the Toaster Interface</link>" 355 see the
356 "<link linkend='using-the-toaster-web-interface'>Using the Toaster Web Interface</link>"
289 section. 357 section.
290 </para> 358 </para>
291 </section> 359 </section>
@@ -303,65 +371,607 @@
303 <section id='setting-up-locally-and-running-in-build-mode'> 371 <section id='setting-up-locally-and-running-in-build-mode'>
304 <title>Setting Up Locally and Running in Build Mode</title> 372 <title>Setting Up Locally and Running in Build Mode</title>
305 373
306 <note><title>REVIEWER NOTE</title> 374 <para>
307 I need the information on how to do this. 375 Follow these steps to set up a local instance of Toaster and
308 </note> 376 then run in Build Mode:
377 <orderedlist>
378 <listitem><para><emphasis>Prepare your Build System:</emphasis>
379 Be sure your system has the Toaster requirements
380 by following the steps in the
381 "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>"
382 section.
383 </para></listitem>
384 <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis>
385 Get the requirements set up so that you can use the
386 Yocto Project to build images.
387 See the
388 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>"
389 section in the Yocto Project Quick Start for information.
390 </para></listitem>
391 <listitem><para><emphasis>Start Toaster:</emphasis>
392 From the root of the source directory (e.g
393 <filename>poky/</filename>), run the following command:
394 <literallayout class='monospaced'>
395 $ bitbake/bin/toaster
396 </literallayout>
397 </para></listitem>
398 <listitem><para><emphasis>Create a Superuser:</emphasis>
399 Django will ask you if you want to create a superuser.
400 You can skip this step, but it is recommended that you
401 create a superuser.
402 You can use the superuser to access the Django
403 administration interface and make changes to the
404 Toaster configuration.
405 </para></listitem>
406 <listitem><para><emphasis>Select the Build Log Directory:</emphasis>
407 Toaster asks you to specify the directory where you
408 want to store the build log files.
409 Choosing a directory for these files makes sure they
410 are always available to you.
411 If you do not choose a directory, the logs can
412 disappear (e.g. deleting the Build Directory).</para>
413 <para>When Toaster prompts you for the Build Log
414 directory, you can select the suggested default
415 or provide a path to a different directory.
416 </para></listitem>
417 <listitem><para><emphasis>Specify the Layer Checkout Directory:</emphasis>
418 Toaster asks you to specify the directory into which
419 layers are checked out.
420 Toaster clones any layers needed for your builds
421 inside this directory.</para>
422 <para>When Toaster prompts you for the Layer
423 checkout directory, you can select the suggested
424 default or provide a path to a different directory.
425 </para></listitem>
426 <listitem><para><emphasis>Specify the Build Directory Path:</emphasis>
427 Toaster asks you to specify the path to the
428 Build Directory.
429 You can select the suggested default or provide a
430 path to a different directory.
431 </para></listitem>
432 <listitem><para><emphasis>Choose Whether or not to Import a Default Toaster Configuration File:</emphasis>
433 Toaster asks you if you want to import a default
434 Toaster configuration file.
435 Toaster configurations are stored in
436 JSON files called
437 <filename>toasterconf.json</filename> and supports
438 several types.
439 For information on JSON files, see the
440 "<link linkend='toaster-json-files'>JSON Files</link>"
441 section.</para>
442 <para>You can skip importing a configuration file
443 by entering "0" at the prompt.
444 However, it is recommended that you import one of the
445 configuration files listed during this step.
446 You can always amend the imported configuration during
447 a later stage through the Django administration
448 interface.</para>
449 <para>For general information on Django, see the
450 available
451 <ulink url='https://docs.djangoproject.com/en/1.7/'>documentation</ulink>.
452 You can also find information on Toaster-specific
453 <filename>manage.py</filename> commands in the
454 "<link linkend='toaster-useful-commands'>Useful Commands</link>"
455 section.
456 </para></listitem>
457 <listitem><para><emphasis>Open the Browser:</emphasis>
458 If no browser window appears, open your favorite
459 browser and enter the following:
460 <literallayout class='monospaced'>
461 http://localhost:8000/toastergui
462 </literallayout>
463 You can now use the Toaster web interface.
464 </para></listitem>
465 </orderedlist>
466 </para>
309 </section> 467 </section>
310 468
311 <section id='setting-up-a-hosted-service-and-running-in-build-mode'> 469 <section id='setting-up-a-hosted-service-and-running-in-build-mode'>
312 <title>Setting Up a Hosted Service and Running in Build Mode</title> 470 <title>Setting Up a Hosted Service and Running in Build Mode</title>
313 471
314 <note><title>REVIEWER NOTE</title> 472 <para>
315 Right now, the 473 Follow these steps to set up a hosted service and run Toaster
316 <ulink url='https://wiki.yoctoproject.org/wiki/Setting_up_a_hosted_managed_mode_for_Toaster'>WIKI PAGE</ulink> 474 in Build Mode:
317 has some information on this but I don't understand it. 475 <orderedlist>
318 I need more information. 476 <listitem><para><emphasis>Prepare your Build System:</emphasis>
319 </note> 477 Be sure your system has the Toaster requirements
478 by following the steps in the
479 "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>"
480 section.
481 </para></listitem>
482 <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis>
483 Get the requirements set up so that you can use the
484 Yocto Project to build images.
485 See the
486 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>"
487 section in the Yocto Project Quick Start for information.
488 </para></listitem>
489 <listitem><para><emphasis>Be Sure Management is Enabled:</emphasis>
490 If you are running Toaster under Apache, you need to
491 be sure management is enabled.
492 To enable management, set
493 <filename>MANAGED</filename> to "True" by adding
494 the following to the
495 <filename>bitbake/lib/toaster/settings.py</filename>
496 file:
497 <literallayout class='monospaced'>
498 MANAGED="True"
499 </literallayout>
500 </para></listitem>
501 <listitem><para><emphasis>Configure the Build Environment:</emphasis>
502 Configure the build environment by running the
503 following:
504 <literallayout class='monospaced'>
505 bitbake/lib/toaster/manage.py checksettings
506 </literallayout>
507 For reference information on Toaster-specific
508 <filename>manage.py</filename> commands, see the
509 "<link linkend='toaster-useful-commands'>Useful Commands</link>"
510 section.
511 </para></listitem>
512 <listitem><para><emphasis>Load a Configuration File:</emphasis>
513 Load a configuration file by running the following:
514 <literallayout class='monospaced'>
515 bitbake/lib/toaster/manage.py loadconf <replaceable>path-to-toasterconf.json-file</replaceable>
516 </literallayout>
517 For reference information on Toaster-specific
518 <filename>manage.py</filename> commands, see the
519 "<link linkend='toaster-useful-commands'>Useful Commands</link>"
520 section.
521 </para></listitem>
522 <listitem><para><emphasis>Set Up Toaster for Normal Usage:</emphasis>
523 You need to configure each build environment, layer
524 sources, and BitBake versions.</para>
525 <para>Verify that your releases have been loaded correctly by
526 using the Toaster web interface to create a new
527 project.
528 Check the "Releases" dropdown menu to be sure your
529 newly specified releases exist.</para>
530 <para>If you want to use the administration interface
531 for this step, here is a set of example commands
532 with some descriptions as an example:
533 <literallayout class='monospaced'>
534 # Create the user under which the builds will run
535 $ adduser poky
536
537 # Bring up the administration interface
538 $xdg-open http://<replaceable>server-address</replaceable>/admin/
539
540 # Login with the admin user previously created
541
542 # Go to the BuildEnvironment object in Build Environments and
543 # set address to local host, sourcedir to /home/poky, and
544 # builddir to /home/pokybuild.
545 #
546 # Save your changes and exit
547
548 # Go to Home, Layer Sources and select add Layer Source
549 # Name: OpenEmbedded, Sourcetype: layerindex,
550 # Apiurl: http://layers openembedded.org/layerindex/api/
551 # Save your changes and exit
552
553 # Go to Home, Bitbake Versions, Add bitbake version;
554 # Take version information from: http://git.openembedded.org/bitbake/refs/heads,
555 # This example assumes "master" version.
556 # set Name: master, Giturl git://git.openembedded.org/bitbake
557 # branch master, dirpath /
558 # Save your changes and exit
559 </literallayout>
560 You also need to configure the project releases, the
561 default variables, and update information from the
562 layer index.
563 Continuing with the example:
564 <literallayout class='monospaced'>
565 # Go to Home, Releases, Add release
566 # set Name: master, Description: Current master release, select Bitbake Version,
567 # and Branch: master
568 # Save your changes and exit
569
570 # Go to Home, Toaster Settings, select the Setting for DEFAULT_RELEASE
571 # set Helptext: This selects the default release., Value: master
572 # Save your changes and exit
573
574 # Go to Home, Bitbake Versions, Add bitbake version;
575 # take version infor from : http://git.openembedded.org/bitbake/refs/heads,
576 # this manual assumes the master version
577 # set Name: master, Giturl git://git.openembedded.org/bitbake
578 # branch master, dirpath /
579 # Save your changes and exit
580
581 # Update the information
582 # bitbake/lib/toaster/manage.py lsupdates
583 </literallayout>
584 For reference information on Toaster-specific
585 <filename>manage.py</filename> commands, see the
586 "<link linkend='toaster-useful-commands'>Useful Commands</link>"
587 section.
588 </para></listitem>
589 <listitem><para><emphasis>Install and Set up the Database Server:</emphasis>
590 You can use any SQL server out of the box.
591 It is recommended that you use
592 <filename>mysql-server</filename> because it has
593 the advantages of advanced SQL features along with a
594 fast and reliable database.
595 However, setting up <filename>mysql-server</filename>
596 is more complex and might require a Database
597 Administrator to tune it.</para>
598 <para>Another supported database backend is
599 <filename>sqlite3</filename>.
600 With <filename>sqlite3</filename>, you have the
601 advantage of no configuration and an easy installation.
602 However, Toaster still requires direct access to the
603 backend.
604 The <filename>sqlite</filename> backend is also slower
605 as compared to <filename>mysql-server</filename>, and
606 has no transactional support.</para>
607 <para>You should set up proper username and password
608 access on the shared database for everyone that will
609 be using Toaster.
610 You need administrator rights for the root account,
611 which is not the same thing as root access on the
612 machine.
613 Here is an example that installs
614 <filename>mysql-server</filename> and sets up
615 some user accounts and the database.
616 <literallayout class='monospaced'>
617 $ apt-get install mysql-server
618 $ mysql -u root
619 mysql> CREATE USER 'newuser'@'localhost' IDENTIFIED BY 'password';
620 mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost';
621 mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost';
622 mysql> CREATE DATABASE 'toaster';
623 </literallayout>
624 You need a separate clone of the
625 <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>
626 for the Database Server.
627 This clone is only used for getting the latest Toaster
628 files.
629 You can set this up using the following Git command.
630 Be sure to set up the directory outside of any
631 Build Directories.
632 <literallayout class='monospaced'>
633 $ git clone git://git.yoctoproject.org/poky
634 </literallayout>
635 In the separately cloned tree for the Database Server,
636 edit the
637 <filename>bitbake/lib/toaster/toastermain/settings.py</filename>
638 file so that the <filename>DATABASES</filename> value
639 points to the previously created database server.
640 Use the username and password established
641 earlier.
642 Here is an example:
643 <literallayout class='monospaced'>
644 $ cat /opt/bitbake/lib/toaster/toastermain/settings.py
645 ...
646 DATABASES = {
647 'default': {
648 'ENGINE': 'django.db.backends.mysql',
649 'NAME': 'toaster',
650 'USER': 'newuser',
651 'PASSWORD': 'password',
652 'HOST': '192.168.0.25',
653 'PORT': '3306',
654 }
655 ...
656 </literallayout>
657 </para></listitem>
658 <listitem><para><emphasis>Create the Database</emphasis>
659 Use the following commands to create the default
660 database structure:
661 <literallayout class='monospaced'>
662 $ bitbake/lib/toaster/manage.py syncdb
663 $ bitbake/lib/toaster/manage.py migrate orm
664 $ bitbake/lib/toaster/manage.py migrate bldcontrol
665 </literallayout>
666 The interface asks you if you want to create a
667 superuser.
668 Do not skip this step.
669 You will use the superuser account to access the
670 administration interface and make changes to the
671 Toaster configuration.
672 </para></listitem>
673 <listitem><para><emphasis>Select Where the Build Process Takes Place:</emphasis>
674 You need to create three directories for storing
675 build artifacts, downloading sources, and running
676 builds.
677 All three directories need to be writable by
678 the "poky" user.
679 The build artifacts directory needs to readable by the
680 apache user.
681 You also need free disk space in the range of
682 100 Gbytes.
683 Following are three suggested directories:
684 <literallayout class='monospaced'>
685 /home/poky/buildartifacts/
686 /home/poky/build/
687 /home/poky/sources/
688 </literallayout>
689 </para></listitem>
690 <listitem><para><emphasis>Set Up the <filename>toasterconf.json</filename> File:</emphasis>
691 Download the <filename>toasterconf.json</filename> file
692 from the
693 <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>File:Toasterconf.json.txt.patch</ulink>
694 wiki page and edit it to suit your environment.
695 For information on the relevant sections of the file,
696 see the
697 "<link linkend='toaster-json-files'>JSON Files</link>"
698 section.
699 </para></listitem>
700 <listitem><para><emphasis>Check the Toaster Settings:</emphasis>
701 You can check the Toaster settings by running this
702 command:
703 <literallayout class='monospaced'>
704 $ bitbake/lib/toaster/manage.py checksettings
705 </literallayout>
706 When prompted, paste in the directory paths created
707 previously during Step 9.
708 Alternatively, you can select the edited
709 <filename>toasterconf.json</filename> file set up in
710 Step 5.
711 </para></listitem>
712 <listitem><para><emphasis>Install and Set Up the Web Server:</emphasis>
713 For a production environment, it is recommended that
714 you install and set up a front-end web server.
715 This server allows for load balancing and
716 multi-threading over Toaster and
717 <filename>django</filename> WSGI.
718 Here is an example that uses Apache web server:
719 <literallayout class='monospaced'>
720 $ apt-get install apache2 libapache2-mod-wsgi
721 $ a2enmod wsgi
722 $ cat /etc/apache2/sites-available/000-default.conf
723
724 ...
725
726 # the WSGIPythonPath is global
727 WSGIPythonPath /opt/bitbake/lib/toaster/
728
729 ...
730
731 #snip - in VirtualHost
732 WSGIScriptAlias / /opt/bitbake/lib/toaster/toastermain/wsgi.py
733
734 &lt;Directory //opt/bitbake/lib/toaster/toastermain/&gt;
735 &lt;Files wsgi.py&gt;
736 Require all granted
737 &lt;/Files&gt;
738 &lt;/Directory&gt;
739
740 ...
741 </literallayout>
742 You need to collect static media from Toaster and
743 continue configuring Apache to serve that static
744 media:
745 <literallayout class='monospaced'>
746 $ mkdir /var/www.html/static &amp;&amp; cd /var/www.html/static
747 $ /opt bitbake/lib/toaster/manage.py collectstatic
748 $ cat /etc/apache2/sites-available/000-default.conf
749
750 ...
751
752 # in VirtualHost, AHEAD of the WSGIScriptAlias definition
753 Alias /static/ /var/www.html/static/
754
755 &lt;Directory /var/www.html/static/&gt;
756 Require all granted
757 &lt;/Directory&gt;
758
759 ...
760
761 WSGIScript Alias / /opt/bitbake/lib/toaster/toastermain/wsgi.py
762
763 ...
764 </literallayout>
765 </para></listitem>
766 <listitem><para><emphasis>Start Toaster:</emphasis>
767 Synchronize the databases for toaster, and then start
768 up the web server.
769 Here is an example that continues with the assumed
770 components from the previous steps:
771 <literallayout class='monospaced'>
772 $ /opt/bitbake/lib/toaster/manage.py syncdb
773 $ /opt/bitbake/lib/toaster/manage.py migrate orm
774 $ /opt/bitbake/lib/toaster/manage.py migrate bldcontrol
775
776 $ service apache2 restart
777 </literallayout>
778 For reference information on the
779 <filename>manage.py</filename> commands used here,
780 see the
781 "<link linkend='toaster-useful-commands'>Useful Commands</link>"
782 section.
783 </para></listitem>
784 <listitem><para><emphasis>Set up Build Control and Open the Web Interface:</emphasis>
785 You need to run the build control manager.
786 You can do this as shown in the following example:
787 <literallayout class='monospaced'>
788 # as the "poky" user, start the runbuilds command in a loop (or put it in crontab!)
789 $ sudo -i -u poky
790 $ while true; do /opt/bitbake/lib/toaster/manage.py runbuilds; sleep 10; done
791
792 # open up the web interface
793 $ xdg-open http://[server-address]/toastergui/
794 </literallayout>
795 It is suggested that you enable build control by
796 setting <filename>runbuilds</filename> in the
797 <filename>crontab</filename> as follows:
798 <literallayout class='monospaced'>
799 $ crontab -l
800 * * * * * /opt/bitbake/lit/toaster/manage.py runbuilds
801 </literallayout>
802 </para></listitem>
803 <listitem><para><emphasis>Open the Browser:</emphasis>
804 Once the Apache server is running, connect to it with
805 your favorite browser and verify that the Toaster
806 interface comes up.
807 You can track accesses and errors in the Apache
808 service logs:
809 <literallayout class='monospaced'>
810 http://localhost:8000/toastergui
811 </literallayout>
812 You can now use the Toaster web interface.
813 </para></listitem>
814 </orderedlist>
815 </para>
320 </section> 816 </section>
321 </section> 817 </section>
322 818
323 <section id='using-the-toaster-interface'> 819 <section id='using-the-toaster-web-interface'>
324 <title>Using the Toaster Interface</title> 820 <title>Using the Toaster Web Interface</title>
325 821
326 <para> 822 <para>
327 The Toaster interface allows you to examine the following: 823 The Toaster web interface allows you to do the following:
328 <itemizedlist> 824 <itemizedlist>
329 <listitem><para> 825 <listitem><para>
330 Outcome of the build, errors and warnings thrown 826 Browse all OpenEmbedded layers available for your
827 selected version of the build system
828 </para></listitem>
829 <listitem><para>
830 Import your own layers for building.
331 </para></listitem> 831 </para></listitem>
332 <listitem><para> 832 <listitem><para>
333 Packages included in an image 833 Add and remove layers from your configuration.
334 </para></listitem> 834 </para></listitem>
335 <listitem><para> 835 <listitem><para>
336 Image directory structure 836 Set configuration variables.
337 </para></listitem> 837 </para></listitem>
338 <listitem><para> 838 <listitem><para>
339 Build configuration 839 Select a target or multiple targets to build.
340 </para></listitem> 840 </para></listitem>
341 <listitem><para> 841 <listitem><para>
342 Recipes and packages built 842 Start your builds.
343 </para></listitem> 843 </para></listitem>
344 <listitem><para> 844 <listitem><para>
345 Full dependency chain for tasks, recipes and packages 845 See what was built (recipes and packages) and what
846 packages were installed into your final image.
346 </para></listitem> 847 </para></listitem>
347 <listitem><para> 848 <listitem><para>
348 Tasks run by the build system 849 Browse the directory structure of your image.
349 </para></listitem> 850 </para></listitem>
350 <listitem><para> 851 <listitem><para>
351 Performance information such as time, CPU usage, and 852 See the value of all variables in your build configuration,
352 disk I/O per task 853 and which files set each value.
854 </para></listitem>
855 <listitem><para>
856 Examine error, warning and trace messages to aid in
857 debugging.
858 </para></listitem>
859 <listitem><para>
860 See information about the BitBake tasks executed and
861 reused during your build, including those that used
862 shared state.
863 </para></listitem>
864 <listitem><para>
865 See dependency relationships between recipes, packages
866 and tasks.
867 </para></listitem>
868 <listitem><para>
869 See performance information such as build time, task time,
870 CPU usage, and disk I/O.
353 </para></listitem> 871 </para></listitem>
354 </itemizedlist> 872 </itemizedlist>
355 For several useful videos that show how to effectively use the 873 Following are several videos that show how to use the Toaster GUI.
356 Toaster interface, see the 874 To get a larger replay of a video after it has started playing,
357 <ulink url='https://www.yoctoproject.org/documentation/toaster-manual-17'>Toaster Documentation</ulink> 875 click in the image title area.
358 on the Yocto Project website.
359 <note><title>REVIEWER NOTE</title>
360 We have agreed to get rid of the manual page on the website,
361 contains the links to the GUI videos.
362 We have agreed to host the videos on Vimeo and to embed the
363 videos in this new Toaster manual.
364 </note>
365 </para> 876 </para>
877
878 <section id='toaster-gui-vids-1'>
879 <title>Toaster Homepage and Table Controls</title>
880
881 <para>
882 This video goes over the Toaster entry page, and provides
883 an overview of the data manipulation capabilities of Toaster,
884 which include search, sorting and filtering by different
885 criteria.
886 <mediaobject>
887 <videoobject>
888 <videodata width="640" height="480" fileref="http://www.youtube.com/v/QEARDnrR1Xw"></videodata>
889 </videoobject>
890 </mediaobject>
891 </para>
892 </section>
893
894 <section id='toaster-gui-vids-2'>
895 <title>Build Dashboard</title>
896
897 <para>
898 This video shows you the build dashboard, a page providing an
899 overview of the information available for a selected build.
900 <mediaobject>
901 <videoobject>
902 <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/KKqHYcnp2gE"></videodata>
903 </videoobject>
904 </mediaobject>
905 </para>
906 </section>
907
908 <section id='toaster-gui-vids-3'>
909 <title>Image Information</title>
910
911 <para>
912 This video walks through the information Toaster provides
913 about images: packages installed and root file system.
914 <mediaobject>
915 <videoobject>
916 <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/XqYGFsmA0Rw"></videodata>
917 </videoobject>
918 </mediaobject>
919 </para>
920 </section>
921
922 <section id='toaster-gui-vids-4'>
923 <title>Configuration</title>
924
925 <para>
926 This video shows the information Toaster provides about build
927 configuration.
928 <mediaobject>
929 <videoobject>
930 <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/UW-j-T2TzIg"></videodata>
931 </videoobject>
932 </mediaobject>
933 </para>
934 </section>
935
936 <section id='toaster-gui-vids-5'>
937 <title>Tasks</title>
938
939 <para>
940 This video shows the information Toaster provides about the
941 tasks run by the build system.
942 <mediaobject>
943 <videoobject>
944 <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/D4-9vGSxQtw"></videodata>
945 </videoobject>
946 </mediaobject>
947 </para>
948 </section>
949
950 <section id='toaster-gui-vids-6'>
951 <title>Recipes and Packages Built</title>
952
953 <para>
954 This video shows the information Toaster provides about recipes
955 and packages built.
956 <mediaobject>
957 <videoobject>
958 <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/x-6dx4huNnw"></videodata>
959 </videoobject>
960 </mediaobject>
961 </para>
962 </section>
963 <section id='toaster-gui-vids-7'>
964 <title>Performance Data</title>
965
966 <para>
967 This video shows the build performance data provided by
968 Toaster.
969 <mediaobject>
970 <videoobject>
971 <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/qWGMrJoqusQ"></videodata>
972 </videoobject>
973 </mediaobject>
974 </para>
975 </section>
366 </section> 976 </section>
367</chapter> 977</chapter>
diff --git a/documentation/toaster-manual/toaster-manual-start.xml b/documentation/toaster-manual/toaster-manual-start.xml
index b884036035..608a505fac 100644
--- a/documentation/toaster-manual/toaster-manual-start.xml
+++ b/documentation/toaster-manual/toaster-manual-start.xml
@@ -9,8 +9,6 @@
9 <para> 9 <para>
10 This chapter describes how you need to prepare your system in order to 10 This chapter describes how you need to prepare your system in order to
11 use Toaster. 11 use Toaster.
12 Toaster requires some packages that you must have installed before
13 trying to run Toaster.
14 </para> 12 </para>
15 13
16 <section id='toaster-setting-up-the-basic-system-requirements'> 14 <section id='toaster-setting-up-the-basic-system-requirements'>
@@ -30,54 +28,103 @@
30 <title>Establishing Toaster System Dependencies</title> 28 <title>Establishing Toaster System Dependencies</title>
31 29
32 <para> 30 <para>
33 Toaster requires extra Python dependencies that Bitbake 31 Toaster requires extra Python dependencies and
34 does not need in order to run. 32 <ulink url='http://www.libslack.org/daemon/'><filename>daemon</filename></ulink>
35 In order to make it easy to run Toaster, a requirements file 33 in order to run.
36 located in the root directory of 34 A Toaster requirements file named
35 <filename>toaster-requirements.txt</filename> defines the
36 Python dependencies.
37 The requirements file is located in the
38 <filename>bitbake</filename> directory, which is located in the
39 root directory of the
37 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> 40 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
38 <filename>bitbake/</filename>
39 (e.g. <filename>poky/bitbake/toaster-requirements.txt</filename>). 41 (e.g. <filename>poky/bitbake/toaster-requirements.txt</filename>).
40 The dependencies appear in a <filename>pip</filename>, 42 The dependencies appear in a <filename>pip</filename>,
41 install-compatible format: 43 install-compatible format.
42 <literallayout class='monospaced'> 44 </para>
43 Django==1.6 45
44 South==0.8.4 46 <section id='toaster-optional-virtual-environment'>
45 argparse==1.2.1 47 <title>Optionally Setting Up a Python Virtual Environment</title>
46 wsgiref==0.1.2 48
47 </literallayout> 49 <para>
48 Follow these steps to get set up: 50 It is highly recommended that you use a Python virtual
49 <orderedlist> 51 environment that allows you to maintain a dedicated Python
50 <listitem><para><emphasis>Install <filename>virtualenv</filename>:</emphasis> 52 executable and its own set of installed modules.
51 <filename>virtualenv</filename> is a tool to create 53 Doing so separates the executable from the Python and modules
52 isolated Python environments by creating folders that 54 provided by the operating system and therefore avoids any
53 contain all the necessary executables to use the packages 55 version conflicts.
54 that Python projects need. 56 </para>
55 You can use <filename>pip</filename> to install 57
56 <filename>virtualenv</filename>: 58 <para>
57 <literallayout class='monospaced'> 59 Follow these steps to set up your virtual environment.
58 $ pip install virtualenv 60 These steps assume a Ubuntu distribution:
59 </literallayout> 61 <orderedlist>
60 </para></listitem> 62 <listitem><para><emphasis>Install <filename>virtualenv</filename>:</emphasis>
61 <listitem><para><emphasis>Create and activate a virtual environment:</emphasis> 63 Install the supported
62 <literallayout class='monospaced'> 64 <filename>python-virtualenv</filename> package from your
65 distribution rather than using <filename>pip</filename>.
66 <literallayout class='monospaced'>
67 $ sudo apt-get install python-virtualenv
68 </literallayout>
69 </para></listitem>
70 <listitem><para><emphasis>Create and Activate a Virtual Environment:</emphasis>
71 <literallayout class='monospaced'>
63 $ virtualenv venv 72 $ virtualenv venv
64 $ source venv/bin/activate 73 $ source venv/bin/activate
65 </literallayout> 74 </literallayout>
66 </para></listitem> 75 </para></listitem>
67 <listitem><para><emphasis>Use <filename>pip</filename> to install needed packages:</emphasis> 76 </orderedlist>
68 <literallayout class='monospaced'> 77 </para>
78 </section>
79
80 <section id='toaster-load-packages'>
81 <title>Install Toaster Packages</title>
82
83 <para>
84 You need to install the packages that Toaster requires.
85 Use this command:
86 <literallayout class='monospaced'>
69 $ pip install -r bitbake/toaster-requirements.txt 87 $ pip install -r bitbake/toaster-requirements.txt
70 </literallayout> 88 </literallayout>
71 </para></listitem> 89 </para>
72 </orderedlist> 90 </section>
73 Once you complete these steps, you execute in a lightweight
74 "virtual environment” with its own site directories that are
75 optionally isolated from system site directories.
76 The virtual environment has its own Python binary
77 (allowing creation of environments with various Python versions)
78 and can have its own independent set of installed Python packages
79 in its site directories.
80 </para>
81 </section>
82 91
92 <section id='toaster-install-daemon'>
93 <title>Install <filename>daemon</filename></title>
94
95 <para>
96 Toaster depends on
97 <ulink url='http://www.libslack.org/daemon/'><filename>daemon</filename></ulink>.
98 Depending on your distribution, how you install
99 <filename>daemon</filename> differs:
100 <itemizedlist>
101 <listitem><para><emphasis>Debian-Based Systems:</emphasis>
102 If you are running a Debian-based distribution,
103 install <filename>daemon</filename> using the
104 following command:
105 <literallayout class='monospaced'>
106 $ sudo apt-get install daemon​
107 </literallayout>
108 </para></listitem>
109 <listitem><para><emphasis>Non-Debian-Based Systems:</emphasis>
110 If you are not running a Debian-based distribution
111 (Redhat-based distribution such as Fedora),
112 you need to download ​the file relevant to the
113 architecture and then install
114 <filename>daemon</filename> manually.
115 Following are the commands for 64-bit distributions:
116 <literallayout class='monospaced'>
117 $ wget http://libslack.org/daemon/download/daemon-0.6.4-1.x86_64.rpm
118 $ sudo rpm -i daemon-0.6.4-1.x86_64.rpm
119 </literallayout>
120 Here are the commands for a 32-bit distribution:
121 <literallayout class='monospaced'>
122 $ wget http://libslack.org/daemon/download/daemon-0.6.4-1.i686.rpm
123 $ sudo rpm -i ​daemon-0.6.4-1.i686.rpm​
124 </literallayout>
125 </para></listitem>
126 </itemizedlist>
127 </para>
128 </section>
129 </section>
83</chapter> 130</chapter>
diff --git a/documentation/toaster-manual/toaster-manual.xml b/documentation/toaster-manual/toaster-manual.xml
index cc27aaa67e..7371ca2b8d 100644
--- a/documentation/toaster-manual/toaster-manual.xml
+++ b/documentation/toaster-manual/toaster-manual.xml
@@ -65,6 +65,8 @@
65 65
66 <xi:include href="toaster-manual-setup-and-use.xml"/> 66 <xi:include href="toaster-manual-setup-and-use.xml"/>
67 67
68 <xi:include href="toaster-manual-reference.xml"/>
69
68</book> 70</book>
69<!-- 71<!--
70vim: expandtab tw=80 ts=4 72vim: expandtab tw=80 ts=4
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-16 09:17:57 +0000