diff options
Diffstat (limited to 'documentation/toaster-manual')
13 files changed, 1557 insertions, 27 deletions
diff --git a/documentation/toaster-manual/history.rst b/documentation/toaster-manual/history.rst new file mode 100644 index 0000000000..027b343d00 --- /dev/null +++ b/documentation/toaster-manual/history.rst | |||
@@ -0,0 +1,46 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | *********************** | ||
4 | Manual Revision History | ||
5 | *********************** | ||
6 | |||
7 | .. list-table:: | ||
8 | :widths: 10 15 40 | ||
9 | :header-rows: 1 | ||
10 | |||
11 | * - Revision | ||
12 | - Date | ||
13 | - Note | ||
14 | * - 1.8 | ||
15 | - April 2015 | ||
16 | - The initial document released with the Yocto Project 1.8 Release | ||
17 | * - 2.0 | ||
18 | - October 2015 | ||
19 | - Released with the Yocto Project 2.0 Release. | ||
20 | * - 2.1 | ||
21 | - April 2016 | ||
22 | - Released with the Yocto Project 2.1 Release. | ||
23 | * - 2.2 | ||
24 | - October 2016 | ||
25 | - Released with the Yocto Project 2.2 Release. | ||
26 | * - 2.3 | ||
27 | - May 2017 | ||
28 | - Released with the Yocto Project 2.3 Release. | ||
29 | * - 2.4 | ||
30 | - October 2017 | ||
31 | - Released with the Yocto Project 2.4 Release. | ||
32 | * - 2.5 | ||
33 | - May 2018 | ||
34 | - Released with the Yocto Project 2.5 Release. | ||
35 | * - 2.6 | ||
36 | - November 2018 | ||
37 | - Released with the Yocto Project 2.6 Release. | ||
38 | * - 2.7 | ||
39 | - May 2019 | ||
40 | - Released with the Yocto Project 2.7 Release. | ||
41 | * - 3.0 | ||
42 | - October 2019 | ||
43 | - Released with the Yocto Project 3.0 Release. | ||
44 | * - 3.1 | ||
45 | - April 2020 | ||
46 | - Released with the Yocto Project 3.1 Release. | ||
diff --git a/documentation/toaster-manual/toaster-manual-customization.xsl b/documentation/toaster-manual/toaster-manual-customization.xsl index d78694ac14..3a9b22eb8e 100644 --- a/documentation/toaster-manual/toaster-manual-customization.xsl +++ b/documentation/toaster-manual/toaster-manual-customization.xsl | |||
@@ -1,4 +1,6 @@ | |||
1 | <?xml version='1.0'?> | 1 | <?xml version='1.0'?> |
2 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
3 | |||
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"> | 4 | <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> |
3 | 5 | ||
4 | <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> | 6 | <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> |
diff --git a/documentation/toaster-manual/toaster-manual-intro.rst b/documentation/toaster-manual/toaster-manual-intro.rst new file mode 100644 index 0000000000..0b7cd41c8f --- /dev/null +++ b/documentation/toaster-manual/toaster-manual-intro.rst | |||
@@ -0,0 +1,105 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ************ | ||
4 | Introduction | ||
5 | ************ | ||
6 | |||
7 | Toaster is a web interface to the Yocto Project's | ||
8 | :term:`OpenEmbedded Build System`. The interface | ||
9 | enables you to configure and run your builds. Information about builds | ||
10 | is collected and stored in a database. You can use Toaster to configure | ||
11 | and start builds on multiple remote build servers. | ||
12 | |||
13 | .. _intro-features: | ||
14 | |||
15 | Toaster Features | ||
16 | ================ | ||
17 | |||
18 | Toaster allows you to configure and run builds, and it provides | ||
19 | extensive information about the build process. | ||
20 | |||
21 | - *Configure and Run Builds:* You can use the Toaster web interface to | ||
22 | configure and start your builds. Builds started using the Toaster web | ||
23 | interface are organized into projects. When you create a project, you | ||
24 | are asked to select a release, or version of the build system you | ||
25 | want to use for the project builds. As shipped, Toaster supports | ||
26 | Yocto Project releases 1.8 and beyond. With the Toaster web | ||
27 | interface, you can: | ||
28 | |||
29 | - Browse layers listed in the various | ||
30 | :ref:`layer sources <toaster-manual/toaster-manual-reference:layer source>` | ||
31 | that are available in your project (e.g. the OpenEmbedded Layer Index at | ||
32 | http://layers.openembedded.org/layerindex/). | ||
33 | |||
34 | - Browse images, recipes, and machines provided by those layers. | ||
35 | |||
36 | - Import your own layers for building. | ||
37 | |||
38 | - Add and remove layers from your configuration. | ||
39 | |||
40 | - Set configuration variables. | ||
41 | |||
42 | - Select a target or multiple targets to build. | ||
43 | |||
44 | - Start your builds. | ||
45 | |||
46 | Toaster also allows you to configure and run your builds from the | ||
47 | command line, and switch between the command line and the web | ||
48 | interface at any time. Builds started from the command line appear | ||
49 | within a special Toaster project called "Command line builds". | ||
50 | |||
51 | - *Information About the Build Process:* Toaster also records extensive | ||
52 | information about your builds. Toaster collects data for builds you | ||
53 | start from the web interface and from the command line as long as | ||
54 | Toaster is running. | ||
55 | |||
56 | .. note:: | ||
57 | |||
58 | You must start Toaster before the build or it will not collect | ||
59 | build data. | ||
60 | |||
61 | With Toaster you can: | ||
62 | |||
63 | - See what was built (recipes and packages) and what packages were | ||
64 | installed into your final image. | ||
65 | |||
66 | - Browse the directory structure of your image. | ||
67 | |||
68 | - See the value of all variables in your build configuration, and | ||
69 | which files set each value. | ||
70 | |||
71 | - Examine error, warning, and trace messages to aid in debugging. | ||
72 | |||
73 | - See information about the BitBake tasks executed and reused during | ||
74 | your build, including those that used shared state. | ||
75 | |||
76 | - See dependency relationships between recipes, packages, and tasks. | ||
77 | |||
78 | - See performance information such as build time, task time, CPU | ||
79 | usage, and disk I/O. | ||
80 | |||
81 | For an overview of Toaster shipped with the Yocto Project &DISTRO; | ||
82 | Release, see the "`Toaster - Yocto Project | ||
83 | 2.2 <https://youtu.be/BlXdOYLgPxA>`__" video. | ||
84 | |||
85 | .. _toaster-installation-options: | ||
86 | |||
87 | Installation Options | ||
88 | ==================== | ||
89 | |||
90 | You can set Toaster up to run as a local instance or as a shared hosted | ||
91 | service. | ||
92 | |||
93 | When Toaster is set up as a local instance, all the components reside on | ||
94 | a single build host. Fundamentally, a local instance of Toaster is | ||
95 | suited for a single user developing on a single build host. | ||
96 | |||
97 | .. image:: figures/simple-configuration.png | ||
98 | :align: center | ||
99 | |||
100 | Toaster as a hosted service is suited for multiple users developing | ||
101 | across several build hosts. When Toaster is set up as a hosted service, | ||
102 | its components can be spread across several machines: | ||
103 | |||
104 | .. image:: figures/hosted-service.png | ||
105 | :align: center | ||
diff --git a/documentation/toaster-manual/toaster-manual-intro.xml b/documentation/toaster-manual/toaster-manual-intro.xml index e84964c4e1..6ee9ec720a 100644 --- a/documentation/toaster-manual/toaster-manual-intro.xml +++ b/documentation/toaster-manual/toaster-manual-intro.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <chapter id='toaster-manual-intro'> | 6 | <chapter id='toaster-manual-intro'> |
6 | <title>Introduction</title> | 7 | <title>Introduction</title> |
diff --git a/documentation/toaster-manual/toaster-manual-reference.rst b/documentation/toaster-manual/toaster-manual-reference.rst new file mode 100644 index 0000000000..e95536e052 --- /dev/null +++ b/documentation/toaster-manual/toaster-manual-reference.rst | |||
@@ -0,0 +1,662 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ********************** | ||
4 | Concepts and Reference | ||
5 | ********************** | ||
6 | |||
7 | In order to configure and use Toaster, you should understand some | ||
8 | concepts and have some basic command reference material available. This | ||
9 | final chapter provides conceptual information on layer sources, | ||
10 | releases, and JSON configuration files. Also provided is a quick look at | ||
11 | some useful ``manage.py`` commands that are Toaster-specific. | ||
12 | Information on ``manage.py`` commands does exist across the Web and the | ||
13 | information in this manual by no means attempts to provide a command | ||
14 | comprehensive reference. | ||
15 | |||
16 | Layer Source | ||
17 | ============ | ||
18 | |||
19 | In general, a "layer source" is a source of information about existing | ||
20 | layers. In particular, we are concerned with layers that you can use | ||
21 | with the Yocto Project and Toaster. This chapter describes a particular | ||
22 | type of layer source called a "layer index." | ||
23 | |||
24 | A layer index is a web application that contains information about a set | ||
25 | of custom layers. A good example of an existing layer index is the | ||
26 | OpenEmbedded Layer Index. A public instance of this layer index exists | ||
27 | at http://layers.openembedded.org. You can find the code for this | ||
28 | layer index's web application at | ||
29 | http://git.yoctoproject.org/cgit/cgit.cgi/layerindex-web/. | ||
30 | |||
31 | When you tie a layer source into Toaster, it can query the layer source | ||
32 | through a | ||
33 | `REST <http://en.wikipedia.org/wiki/Representational_state_transfer>`__ | ||
34 | API, store the information about the layers in the Toaster database, and | ||
35 | then show the information to users. Users are then able to view that | ||
36 | information and build layers from Toaster itself without worrying about | ||
37 | cloning or editing the BitBake layers configuration file | ||
38 | ``bblayers.conf``. | ||
39 | |||
40 | Tying a layer source into Toaster is convenient when you have many | ||
41 | custom layers that need to be built on a regular basis by a community of | ||
42 | developers. In fact, Toaster comes pre-configured with the OpenEmbedded | ||
43 | Metadata Index. | ||
44 | |||
45 | .. note:: | ||
46 | |||
47 | You do not have to use a layer source to use Toaster. Tying into a | ||
48 | layer source is optional. | ||
49 | |||
50 | .. _layer-source-using-with-toaster: | ||
51 | |||
52 | Setting Up and Using a Layer Source | ||
53 | ----------------------------------- | ||
54 | |||
55 | To use your own layer source, you need to set up the layer source and | ||
56 | then tie it into Toaster. This section describes how to tie into a layer | ||
57 | index in a manner similar to the way Toaster ties into the OpenEmbedded | ||
58 | Metadata Index. | ||
59 | |||
60 | Understanding Your Layers | ||
61 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
62 | |||
63 | The obvious first step for using a layer index is to have several custom | ||
64 | layers that developers build and access using the Yocto Project on a | ||
65 | regular basis. This set of layers needs to exist and you need to be | ||
66 | familiar with where they reside. You will need that information when you | ||
67 | set up the code for the web application that "hooks" into your set of | ||
68 | layers. | ||
69 | |||
70 | For general information on layers, see the | ||
71 | ":ref:`overview-manual/overview-manual-yp-intro:the yocto project layer model`" | ||
72 | section in the Yocto Project Overview and Concepts Manual. For information on how | ||
73 | to create layers, see the ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" | ||
74 | section in the Yocto Project Development Tasks Manual. | ||
75 | |||
76 | .. _configuring-toaster-to-hook-into-your-layer-source: | ||
77 | |||
78 | Configuring Toaster to Hook Into Your Layer Index | ||
79 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
80 | |||
81 | If you want Toaster to use your layer index, you must host the web | ||
82 | application in a server to which Toaster can connect. You also need to | ||
83 | give Toaster the information about your layer index. In other words, you | ||
84 | have to configure Toaster to use your layer index. This section | ||
85 | describes two methods by which you can configure and use your layer | ||
86 | index. | ||
87 | |||
88 | In the previous section, the code for the OpenEmbedded Metadata Index | ||
89 | (i.e. http://layers.openembedded.org) was referenced. You can use | ||
90 | this code, which is at | ||
91 | http://git.yoctoproject.org/cgit/cgit.cgi/layerindex-web/, as a | ||
92 | base to create your own layer index. | ||
93 | |||
94 | Use the Administration Interface | ||
95 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
96 | |||
97 | Access the administration interface through a browser by entering the | ||
98 | URL of your Toaster instance and adding "``/admin``" to the end of the | ||
99 | URL. As an example, if you are running Toaster locally, use the | ||
100 | following URL:: | ||
101 | |||
102 | http://127.0.0.1:8000/admin | ||
103 | |||
104 | The administration interface has a "Layer sources" section that includes | ||
105 | an "Add layer source" button. Click that button and provide the required | ||
106 | information. Make sure you select "layerindex" as the layer source type. | ||
107 | |||
108 | Use the Fixture Feature | ||
109 | ^^^^^^^^^^^^^^^^^^^^^^^ | ||
110 | |||
111 | The Django fixture feature overrides the default layer server when you | ||
112 | use it to specify a custom URL. To use the fixture feature, create (or | ||
113 | edit) the file ``bitbake/lib/toaster.orm/fixtures/custom.xml``, and then | ||
114 | set the following Toaster setting to your custom URL: | ||
115 | |||
116 | .. code-block:: xml | ||
117 | |||
118 | <?xml version="1.0" ?> | ||
119 | <django-objects version="1.0"> | ||
120 | <object model="orm.toastersetting" pk="100"> | ||
121 | <field name="name" type="CharField">CUSTOM_LAYERINDEX_SERVER</field> | ||
122 | <field name="value" type="CharField">https://layers.my_organization.org/layerindex/branch/master/layers/</field> | ||
123 | </object> | ||
124 | <django-objects> | ||
125 | |||
126 | When you start Toaster for the first time, or | ||
127 | if you delete the file ``toaster.sqlite`` and restart, the database will | ||
128 | populate cleanly from this layer index server. | ||
129 | |||
130 | Once the information has been updated, verify the new layer information | ||
131 | is available by using the Toaster web interface. To do that, visit the | ||
132 | "All compatible layers" page inside a Toaster project. The layers from | ||
133 | your layer source should be listed there. | ||
134 | |||
135 | If you change the information in your layer index server, refresh the | ||
136 | Toaster database by running the following command: | ||
137 | |||
138 | .. code-block:: shell | ||
139 | |||
140 | $ bitbake/lib/toaster/manage.py lsupdates | ||
141 | |||
142 | |||
143 | If Toaster can reach the API URL, you should see a message telling you that | ||
144 | Toaster is updating the layer source information. | ||
145 | |||
146 | .. _toaster-releases: | ||
147 | |||
148 | Releases | ||
149 | ======== | ||
150 | |||
151 | When you create a Toaster project using the web interface, you are asked | ||
152 | to choose a "Release." In the context of Toaster, the term "Release" | ||
153 | refers to a set of layers and a BitBake version the OpenEmbedded build | ||
154 | system uses to build something. As shipped, Toaster is pre-configured | ||
155 | with releases that correspond to Yocto Project release branches. | ||
156 | However, you can modify, delete, and create new releases according to | ||
157 | your needs. This section provides some background information on | ||
158 | releases. | ||
159 | |||
160 | .. _toaster-releases-supported: | ||
161 | |||
162 | Pre-Configured Releases | ||
163 | ----------------------- | ||
164 | |||
165 | As shipped, Toaster is configured to use a specific set of releases. Of | ||
166 | course, you can always configure Toaster to use any release. For | ||
167 | example, you might want your project to build against a specific commit | ||
168 | of any of the "out-of-the-box" releases. Or, you might want your project | ||
169 | to build against different revisions of OpenEmbedded and BitBake. | ||
170 | |||
171 | As shipped, Toaster is configured to work with the following releases: | ||
172 | |||
173 | - *Yocto Project &DISTRO; "&DISTRO_NAME;" or OpenEmbedded "&DISTRO_NAME;":* | ||
174 | This release causes your Toaster projects to build against the head | ||
175 | of the &DISTRO_NAME_NO_CAP; branch at | ||
176 | https://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=&DISTRO_NAME_NO_CAP; or | ||
177 | http://git.openembedded.org/openembedded-core/commit/?h=&DISTRO_NAME_NO_CAP;. | ||
178 | |||
179 | - *Yocto Project "Master" or OpenEmbedded "Master":* This release | ||
180 | causes your Toaster Projects to build against the head of the master | ||
181 | branch, which is where active development takes place, at | ||
182 | https://git.yoctoproject.org/cgit/cgit.cgi/poky/log/ or | ||
183 | http://git.openembedded.org/openembedded-core/log/. | ||
184 | |||
185 | - *Local Yocto Project or Local OpenEmbedded:* This release causes your | ||
186 | Toaster Projects to build against the head of the ``poky`` or | ||
187 | ``openembedded-core`` clone you have local to the machine running | ||
188 | Toaster. | ||
189 | |||
190 | Configuring Toaster | ||
191 | =================== | ||
192 | |||
193 | In order to use Toaster, you must configure the database with the | ||
194 | default content. The following subsections describe various aspects of | ||
195 | Toaster configuration. | ||
196 | |||
197 | Configuring the Workflow | ||
198 | ------------------------ | ||
199 | |||
200 | The ``bldcontrol/management/commands/checksettings.py`` file controls | ||
201 | workflow configuration. The following steps outline the process to | ||
202 | initially populate this database. | ||
203 | |||
204 | 1. The default project settings are set from | ||
205 | ``orm/fixtures/settings.xml``. | ||
206 | |||
207 | 2. The default project distro and layers are added from | ||
208 | ``orm/fixtures/poky.xml`` if poky is installed. If poky is not | ||
209 | installed, they are added from ``orm/fixtures/oe-core.xml``. | ||
210 | |||
211 | 3. If the ``orm/fixtures/custom.xml`` file exists, then its values are | ||
212 | added. | ||
213 | |||
214 | 4. The layer index is then scanned and added to the database. | ||
215 | |||
216 | Once these steps complete, Toaster is set up and ready to use. | ||
217 | |||
218 | Customizing Pre-Set Data | ||
219 | ------------------------ | ||
220 | |||
221 | The pre-set data for Toaster is easily customizable. You can create the | ||
222 | ``orm/fixtures/custom.xml`` file to customize the values that go into to | ||
223 | the database. Customization is additive, and can either extend or | ||
224 | completely replace the existing values. | ||
225 | |||
226 | You use the ``orm/fixtures/custom.xml`` file to change the default | ||
227 | project settings for the machine, distro, file images, and layers. When | ||
228 | creating a new project, you can use the file to define the offered | ||
229 | alternate project release selections. For example, you can add one or | ||
230 | more additional selections that present custom layer sets or distros, | ||
231 | and any other local or proprietary content. | ||
232 | |||
233 | Additionally, you can completely disable the content from the | ||
234 | ``oe-core.xml`` and ``poky.xml`` files by defining the section shown | ||
235 | below in the ``settings.xml`` file. For example, this option is | ||
236 | particularly useful if your custom configuration defines fewer releases | ||
237 | or layers than the default fixture files. | ||
238 | |||
239 | The following example sets "name" to "CUSTOM_XML_ONLY" and its value to | ||
240 | "True". | ||
241 | |||
242 | .. code-block:: xml | ||
243 | |||
244 | <object model="orm.toastersetting" pk="99"> | ||
245 | <field type="CharField" name="name">CUSTOM_XML_ONLY</field> | ||
246 | <field type="CharField" name="value">True</field> | ||
247 | </object> | ||
248 | |||
249 | Understanding Fixture File Format | ||
250 | --------------------------------- | ||
251 | |||
252 | The following is an overview of the file format used by the | ||
253 | ``oe-core.xml``, ``poky.xml``, and ``custom.xml`` files. | ||
254 | |||
255 | The following subsections describe each of the sections in the fixture | ||
256 | files, and outline an example section of the XML code. you can use to | ||
257 | help understand this information and create a local ``custom.xml`` file. | ||
258 | |||
259 | Defining the Default Distro and Other Values | ||
260 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
261 | |||
262 | This section defines the default distro value for new projects. By | ||
263 | default, it reserves the first Toaster Setting record "1". The following | ||
264 | demonstrates how to set the project default value for | ||
265 | :term:`DISTRO`: | ||
266 | |||
267 | .. code-block:: xml | ||
268 | |||
269 | <!-- Set the project default value for DISTRO --> | ||
270 | <object model="orm.toastersetting" pk="1"> | ||
271 | <field type="CharField" name="name">DEFCONF_DISTRO</field> | ||
272 | <field type="CharField" name="value">poky</field> | ||
273 | </object> | ||
274 | |||
275 | You can override | ||
276 | other default project values by adding additional Toaster Setting | ||
277 | sections such as any of the settings coming from the ``settings.xml`` | ||
278 | file. Also, you can add custom values that are included in the BitBake | ||
279 | environment. The "pk" values must be unique. By convention, values that | ||
280 | set default project values have a "DEFCONF" prefix. | ||
281 | |||
282 | Defining BitBake Version | ||
283 | ~~~~~~~~~~~~~~~~~~~~~~~~ | ||
284 | |||
285 | The following defines which version of BitBake is used for the following | ||
286 | release selection: | ||
287 | |||
288 | .. code-block:: xml | ||
289 | |||
290 | <!-- Bitbake versions which correspond to the metadata release --> | ||
291 | <object model="orm.bitbakeversion" pk="1"> | ||
292 | <field type="CharField" name="name">&DISTRO_NAME_NO_CAP;</field> | ||
293 | <field type="CharField" name="giturl">git://git.yoctoproject.org/poky</field> | ||
294 | <field type="CharField" name="branch">&DISTRO_NAME_NO_CAP;</field> | ||
295 | <field type="CharField" name="dirpath">bitbake</field> | ||
296 | </object> | ||
297 | |||
298 | .. _defining-releases: | ||
299 | |||
300 | Defining Release | ||
301 | ~~~~~~~~~~~~~~~~ | ||
302 | |||
303 | The following defines the releases when you create a new project: | ||
304 | |||
305 | .. code-block:: xml | ||
306 | |||
307 | <!-- Releases available --> | ||
308 | <object model="orm.release" pk="1"> | ||
309 | <field type="CharField" name="name">&DISTRO_NAME_NO_CAP;</field> | ||
310 | <field type="CharField" name="description">Yocto Project &DISTRO; "&DISTRO_NAME;"</field> | ||
311 | <field rel="ManyToOneRel" to="orm.bitbakeversion" name="bitbake_version">1</field> | ||
312 | <field type="CharField" name="branch_name">&DISTRO_NAME_NO_CAP;</field> | ||
313 | <field type="TextField" name="helptext">Toaster will run your builds using the tip of the <a href="http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=&DISTRO_NAME_NO_CAP;">Yocto Project &DISTRO_NAME; branch</a>.</field> | ||
314 | </object> | ||
315 | |||
316 | The "pk" value must match the above respective BitBake version record. | ||
317 | |||
318 | Defining the Release Default Layer Names | ||
319 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
320 | |||
321 | The following defines the default layers for each release: | ||
322 | |||
323 | .. code-block:: xml | ||
324 | |||
325 | <!-- Default project layers for each release --> | ||
326 | <object model="orm.releasedefaultlayer" pk="1"> | ||
327 | <field rel="ManyToOneRel" to="orm.release" name="release">1</field> | ||
328 | <field type="CharField" name="layer_name">openembedded-core</field> | ||
329 | </object> | ||
330 | |||
331 | The 'pk' values in the example above should start at "1" and increment | ||
332 | uniquely. You can use the same layer name in multiple releases. | ||
333 | |||
334 | Defining Layer Definitions | ||
335 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
336 | |||
337 | Layer definitions are the most complex. The following defines each of | ||
338 | the layers, and then defines the exact layer version of the layer used | ||
339 | for each respective release. You must have one ``orm.layer`` entry for | ||
340 | each layer. Then, with each entry you need a set of | ||
341 | ``orm.layer_version`` entries that connects the layer with each release | ||
342 | that includes the layer. In general all releases include the layer. | ||
343 | |||
344 | .. code-block:: xml | ||
345 | |||
346 | <object model="orm.layer" pk="1"> | ||
347 | <field type="CharField" name="name">openembedded-core</field> | ||
348 | <field type="CharField" name="layer_index_url"></field> | ||
349 | <field type="CharField" name="vcs_url">git://git.yoctoproject.org/poky</field> | ||
350 | <field type="CharField" name="vcs_web_url">http://git.yoctoproject.org/cgit/cgit.cgi/poky</field> | ||
351 | <field type="CharField" name="vcs_web_tree_base_url">http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%</field> | ||
352 | <field type="CharField" name="vcs_web_file_base_url">http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%</field> | ||
353 | </object> | ||
354 | <object model="orm.layer_version" pk="1"> | ||
355 | <field rel="ManyToOneRel" to="orm.layer" name="layer">1</field> | ||
356 | <field type="IntegerField" name="layer_source">0</field> | ||
357 | <field rel="ManyToOneRel" to="orm.release" name="release">1</field> | ||
358 | <field type="CharField" name="branch">&DISTRO_NAME_NO_CAP;</field> | ||
359 | <field type="CharField" name="dirpath">meta</field> | ||
360 | </object> <object model="orm.layer_version" pk="2"> | ||
361 | <field rel="ManyToOneRel" to="orm.layer" name="layer">1</field> | ||
362 | <field type="IntegerField" name="layer_source">0</field> | ||
363 | <field rel="ManyToOneRel" to="orm.release" name="release">2</field> | ||
364 | <field type="CharField" name="branch">HEAD</field> | ||
365 | <field type="CharField" name="commit">HEAD</field> | ||
366 | <field type="CharField" name="dirpath">meta</field> | ||
367 | </object> | ||
368 | <object model="orm.layer_version" pk="3"> | ||
369 | <field rel="ManyToOneRel" to="orm.layer" name="layer">1</field> | ||
370 | <field type="IntegerField" name="layer_source">0</field> | ||
371 | <field rel="ManyToOneRel" to="orm.release" name="release">3</field> | ||
372 | <field type="CharField" name="branch">master</field> | ||
373 | <field type="CharField" name="dirpath">meta</field> | ||
374 | </object> | ||
375 | |||
376 | The layer "pk" values above must be unique, and typically start at "1". The | ||
377 | layer version "pk" values must also be unique across all layers, and typically | ||
378 | start at "1". | ||
379 | |||
380 | Remote Toaster Monitoring | ||
381 | ========================= | ||
382 | |||
383 | Toaster has an API that allows remote management applications to | ||
384 | directly query the state of the Toaster server and its builds in a | ||
385 | machine-to-machine manner. This API uses the | ||
386 | `REST <http://en.wikipedia.org/wiki/Representational_state_transfer>`__ | ||
387 | interface and the transfer of JSON files. For example, you might monitor | ||
388 | a build inside a container through well supported known HTTP ports in | ||
389 | order to easily access a Toaster server inside the container. In this | ||
390 | example, when you use this direct JSON API, you avoid having web page | ||
391 | parsing against the display the user sees. | ||
392 | |||
393 | Checking Health | ||
394 | --------------- | ||
395 | |||
396 | Before you use remote Toaster monitoring, you should do a health check. | ||
397 | To do this, ping the Toaster server using the following call to see if | ||
398 | it is still alive:: | ||
399 | |||
400 | http://host:port/health | ||
401 | |||
402 | Be sure to provide values for host and port. If the server is alive, you will | ||
403 | get the response HTML: | ||
404 | |||
405 | .. code-block:: html | ||
406 | |||
407 | <!DOCTYPE html> | ||
408 | <html lang="en"> | ||
409 | <head><title>Toaster Health</title></head> | ||
410 | <body>Ok</body> | ||
411 | </html> | ||
412 | |||
413 | Determining Status of Builds in Progress | ||
414 | ---------------------------------------- | ||
415 | |||
416 | Sometimes it is useful to determine the status of a build in progress. | ||
417 | To get the status of pending builds, use the following call:: | ||
418 | |||
419 | http://host:port/toastergui/api/building | ||
420 | |||
421 | Be sure to provide values for host and port. The output is a JSON file that | ||
422 | itemizes all builds in progress. This file includes the time in seconds since | ||
423 | each respective build started as well as the progress of the cloning, parsing, | ||
424 | and task execution. The following is sample output for a build in progress: | ||
425 | |||
426 | .. code-block:: JSON | ||
427 | |||
428 | {"count": 1, | ||
429 | "building": [ | ||
430 | {"machine": "beaglebone", | ||
431 | "seconds": "463.869", | ||
432 | "task": "927:2384", | ||
433 | "distro": "poky", | ||
434 | "clone": "1:1", | ||
435 | "id": 2, | ||
436 | "start": "2017-09-22T09:31:44.887Z", | ||
437 | "name": "20170922093200", | ||
438 | "parse": "818:818", | ||
439 | "project": "my_rocko", | ||
440 | "target": "core-image-minimal" | ||
441 | }] | ||
442 | } | ||
443 | |||
444 | The JSON data for this query is returned in a | ||
445 | single line. In the previous example the line has been artificially | ||
446 | split for readability. | ||
447 | |||
448 | Checking Status of Builds Completed | ||
449 | ----------------------------------- | ||
450 | |||
451 | Once a build is completed, you get the status when you use the following | ||
452 | call:: | ||
453 | |||
454 | http://host:port/toastergui/api/builds | ||
455 | |||
456 | Be sure to provide values for host and port. The output is a JSON file that | ||
457 | itemizes all complete builds, and includes build summary information. The | ||
458 | following is sample output for a completed build: | ||
459 | |||
460 | .. code-block:: JSON | ||
461 | |||
462 | {"count": 1, | ||
463 | "builds": [ | ||
464 | {"distro": "poky", | ||
465 | "errors": 0, | ||
466 | "machine": "beaglebone", | ||
467 | "project": "my_rocko", | ||
468 | "stop": "2017-09-22T09:26:36.017Z", | ||
469 | "target": "quilt-native", | ||
470 | "seconds": "78.193", | ||
471 | "outcome": "Succeeded", | ||
472 | "id": 1, | ||
473 | "start": "2017-09-22T09:25:17.824Z", | ||
474 | "warnings": 1, | ||
475 | "name": "20170922092618" | ||
476 | }] | ||
477 | } | ||
478 | |||
479 | The JSON data for this query is returned in a single line. In the | ||
480 | previous example the line has been artificially split for readability. | ||
481 | |||
482 | Determining Status of a Specific Build | ||
483 | -------------------------------------- | ||
484 | |||
485 | Sometimes it is useful to determine the status of a specific build. To | ||
486 | get the status of a specific build, use the following call:: | ||
487 | |||
488 | http://host:port/toastergui/api/build/ID | ||
489 | |||
490 | Be sure to provide values for | ||
491 | host, port, and ID. You can find the value for ID from the Builds | ||
492 | Completed query. See the ":ref:`toaster-manual/toaster-manual-reference:checking status of builds completed`" | ||
493 | section for more information. | ||
494 | |||
495 | The output is a JSON file that itemizes the specific build and includes | ||
496 | build summary information. The following is sample output for a specific | ||
497 | build: | ||
498 | |||
499 | .. code-block:: JSON | ||
500 | |||
501 | {"build": | ||
502 | {"distro": "poky", | ||
503 | "errors": 0, | ||
504 | "machine": "beaglebone", | ||
505 | "project": "my_rocko", | ||
506 | "stop": "2017-09-22T09:26:36.017Z", | ||
507 | "target": "quilt-native", | ||
508 | "seconds": "78.193", | ||
509 | "outcome": "Succeeded", | ||
510 | "id": 1, | ||
511 | "start": "2017-09-22T09:25:17.824Z", | ||
512 | "warnings": 1, | ||
513 | "name": "20170922092618", | ||
514 | "cooker_log": "/opt/user/poky/build-toaster-2/tmp/log/cooker/beaglebone/build_20170922_022607.991.log" | ||
515 | } | ||
516 | } | ||
517 | |||
518 | The JSON data for this query is returned in a single line. In the | ||
519 | previous example the line has been artificially split for readability. | ||
520 | |||
521 | .. _toaster-useful-commands: | ||
522 | |||
523 | Useful Commands | ||
524 | =============== | ||
525 | |||
526 | In addition to the web user interface and the scripts that start and | ||
527 | stop Toaster, command-line commands exist through the ``manage.py`` | ||
528 | management script. You can find general documentation on ``manage.py`` | ||
529 | at the | ||
530 | `Django <https://docs.djangoproject.com/en/2.2/topics/settings/>`__ | ||
531 | site. However, several ``manage.py`` commands have been created that are | ||
532 | specific to Toaster and are used to control configuration and back-end | ||
533 | tasks. You can locate these commands in the | ||
534 | :term:`Source Directory` (e.g. ``poky``) at | ||
535 | ``bitbake/lib/manage.py``. This section documents those commands. | ||
536 | |||
537 | .. note:: | ||
538 | |||
539 | - When using ``manage.py`` commands given a default configuration, | ||
540 | you must be sure that your working directory is set to the | ||
541 | :term:`Build Directory`. Using | ||
542 | ``manage.py`` commands from the Build Directory allows Toaster to | ||
543 | find the ``toaster.sqlite`` file, which is located in the Build | ||
544 | Directory. | ||
545 | |||
546 | - For non-default database configurations, it is possible that you | ||
547 | can use ``manage.py`` commands from a directory other than the | ||
548 | Build Directory. To do so, the ``toastermain/settings.py`` file | ||
549 | must be configured to point to the correct database backend. | ||
550 | |||
551 | .. _toaster-command-buildslist: | ||
552 | |||
553 | ``buildslist`` | ||
554 | -------------- | ||
555 | |||
556 | The ``buildslist`` command lists all builds that Toaster has recorded. | ||
557 | Access the command as follows: | ||
558 | |||
559 | .. code-block:: shell | ||
560 | |||
561 | $ bitbake/lib/toaster/manage.py buildslist | ||
562 | |||
563 | The command returns a list, which includes numeric | ||
564 | identifications, of the builds that Toaster has recorded in the current | ||
565 | database. | ||
566 | |||
567 | You need to run the ``buildslist`` command first to identify existing | ||
568 | builds in the database before using the | ||
569 | :ref:`toaster-manual/toaster-manual-reference:\`\`builddelete\`\`` command. Here is an | ||
570 | example that assumes default repository and build directory names: | ||
571 | |||
572 | .. code-block:: shell | ||
573 | |||
574 | $ cd ~/poky/build | ||
575 | $ python ../bitbake/lib/toaster/manage.py buildslist | ||
576 | |||
577 | If your Toaster database had only one build, the above | ||
578 | :ref:`toaster-manual/toaster-manual-reference:\`\`buildslist\`\`` | ||
579 | command would return something like the following:: | ||
580 | |||
581 | 1: qemux86 poky core-image-minimal | ||
582 | |||
583 | .. _toaster-command-builddelete: | ||
584 | |||
585 | ``builddelete`` | ||
586 | --------------- | ||
587 | |||
588 | The ``builddelete`` command deletes data associated with a build. Access | ||
589 | the command as follows: | ||
590 | |||
591 | .. code-block:: | ||
592 | |||
593 | $ bitbake/lib/toaster/manage.py builddelete build_id | ||
594 | |||
595 | The command deletes all the build data for the specified | ||
596 | build_id. This command is useful for removing old and unused data from | ||
597 | the database. | ||
598 | |||
599 | Prior to running the ``builddelete`` command, you need to get the ID | ||
600 | associated with builds by using the | ||
601 | :ref:`toaster-manual/toaster-manual-reference:\`\`buildslist\`\`` command. | ||
602 | |||
603 | .. _toaster-command-perf: | ||
604 | |||
605 | ``perf`` | ||
606 | -------- | ||
607 | |||
608 | The ``perf`` command measures Toaster performance. Access the command as | ||
609 | follows: | ||
610 | |||
611 | .. code-block:: shell | ||
612 | |||
613 | $ bitbake/lib/toaster/manage.py perf | ||
614 | |||
615 | The command is a sanity check that returns page loading times in order to | ||
616 | identify performance problems. | ||
617 | |||
618 | .. _toaster-command-checksettings: | ||
619 | |||
620 | ``checksettings`` | ||
621 | ----------------- | ||
622 | |||
623 | The ``checksettings`` command verifies existing Toaster settings. Access | ||
624 | the command as follows: | ||
625 | |||
626 | .. code-block:: shell | ||
627 | |||
628 | $ bitbake/lib/toaster/manage.py checksettings | ||
629 | |||
630 | Toaster uses settings that are based on the database to configure the | ||
631 | building tasks. The ``checksettings`` command verifies that the database | ||
632 | settings are valid in the sense that they have the minimal information | ||
633 | needed to start a build. | ||
634 | |||
635 | In order for the ``checksettings`` command to work, the database must be | ||
636 | correctly set up and not have existing data. To be sure the database is | ||
637 | ready, you can run the following: | ||
638 | |||
639 | .. code-block:: shell | ||
640 | |||
641 | $ bitbake/lib/toaster/manage.py syncdb | ||
642 | $ bitbake/lib/toaster/manage.py migrate orm | ||
643 | $ bitbake/lib/toaster/manage.py migrate bldcontrol | ||
644 | |||
645 | After running these commands, you can run the ``checksettings`` command. | ||
646 | |||
647 | .. _toaster-command-runbuilds: | ||
648 | |||
649 | ``runbuilds`` | ||
650 | ------------- | ||
651 | |||
652 | The ``runbuilds`` command launches scheduled builds. Access the command | ||
653 | as follows: | ||
654 | |||
655 | .. code-block:: shell | ||
656 | |||
657 | $ bitbake/lib/toaster/manage.py runbuilds | ||
658 | |||
659 | The ``runbuilds`` command checks if scheduled builds exist in the database | ||
660 | and then launches them per schedule. The command returns after the builds | ||
661 | start but before they complete. The Toaster Logging Interface records and | ||
662 | updates the database when the builds complete. | ||
diff --git a/documentation/toaster-manual/toaster-manual-reference.xml b/documentation/toaster-manual/toaster-manual-reference.xml index 7440580e7c..ae267f4184 100644 --- a/documentation/toaster-manual/toaster-manual-reference.xml +++ b/documentation/toaster-manual/toaster-manual-reference.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <chapter id='toaster-manual-reference'> | 6 | <chapter id='toaster-manual-reference'> |
6 | 7 | ||
diff --git a/documentation/toaster-manual/toaster-manual-setup-and-use.rst b/documentation/toaster-manual/toaster-manual-setup-and-use.rst new file mode 100644 index 0000000000..01c0dce41f --- /dev/null +++ b/documentation/toaster-manual/toaster-manual-setup-and-use.rst | |||
@@ -0,0 +1,651 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | .. Set default pygment highlighting to 'shell' for this document | ||
3 | .. highlight:: shell | ||
4 | |||
5 | **************************** | ||
6 | Setting Up and Using Toaster | ||
7 | **************************** | ||
8 | |||
9 | Starting Toaster for Local Development | ||
10 | ====================================== | ||
11 | |||
12 | Once you have set up the Yocto Project and installed the Toaster system | ||
13 | dependencies as described in the ":ref:`toaster-manual/toaster-manual-start:Preparing to Use | ||
14 | Toaster`" chapter, you are ready to start | ||
15 | Toaster. | ||
16 | |||
17 | Navigate to the root of your | ||
18 | :term:`Source Directory` (e.g. ``poky``):: | ||
19 | |||
20 | $ cd poky | ||
21 | |||
22 | Once in that directory, source the build environment script:: | ||
23 | |||
24 | $ source oe-init-build-env | ||
25 | |||
26 | Next, from the build directory (e.g. | ||
27 | ``poky/build``), start Toaster using this command:: | ||
28 | |||
29 | $ source toaster start | ||
30 | |||
31 | You can now run your builds from the command line, or with Toaster | ||
32 | as explained in section | ||
33 | ":ref:`toaster-manual/toaster-manual-setup-and-use:using the toaster web interface`". | ||
34 | |||
35 | To access the Toaster web interface, open your favorite browser and | ||
36 | enter the following:: | ||
37 | |||
38 | http://127.0.0.1:8000 | ||
39 | |||
40 | Setting a Different Port | ||
41 | ======================== | ||
42 | |||
43 | By default, Toaster starts on port 8000. You can use the ``WEBPORT`` | ||
44 | parameter to set a different port. For example, the following command | ||
45 | sets the port to "8400":: | ||
46 | |||
47 | $ source toaster start webport=8400 | ||
48 | |||
49 | Setting Up Toaster Without a Web Server | ||
50 | ======================================= | ||
51 | |||
52 | You can start a Toaster environment without starting its web server. | ||
53 | This is useful for the following: | ||
54 | |||
55 | - Capturing a command-line build's statistics into the Toaster database | ||
56 | for examination later. | ||
57 | |||
58 | - Capturing a command-line build's statistics when the Toaster server | ||
59 | is already running. | ||
60 | |||
61 | - Having one instance of the Toaster web server track and capture | ||
62 | multiple command-line builds, where each build is started in its own | ||
63 | "noweb" Toaster environment. | ||
64 | |||
65 | The following commands show how to start a Toaster environment without | ||
66 | starting its web server, perform BitBake operations, and then shut down | ||
67 | the Toaster environment. Once the build is complete, you can close the | ||
68 | Toaster environment. Before closing the environment, however, you should | ||
69 | allow a few minutes to ensure the complete transfer of its BitBake build | ||
70 | statistics to the Toaster database. If you have a separate Toaster web | ||
71 | server instance running, you can watch this command-line build's | ||
72 | progress and examine the results as soon as they are posted:: | ||
73 | |||
74 | $ source toaster start noweb | ||
75 | $ bitbake target | ||
76 | $ source toaster stop | ||
77 | |||
78 | Setting Up Toaster Without a Build Server | ||
79 | ========================================= | ||
80 | |||
81 | You can start a Toaster environment with the "New Projects" feature | ||
82 | disabled. Doing so is useful for the following: | ||
83 | |||
84 | - Sharing your build results over the web server while blocking others | ||
85 | from starting builds on your host. | ||
86 | |||
87 | - Allowing only local command-line builds to be captured into the | ||
88 | Toaster database. | ||
89 | |||
90 | Use the following command to set up Toaster without a build server:: | ||
91 | |||
92 | $ source toaster start nobuild webport=port | ||
93 | |||
94 | Setting up External Access | ||
95 | ========================== | ||
96 | |||
97 | By default, Toaster binds to the loop back address (i.e. ``localhost``), | ||
98 | which does not allow access from external hosts. To allow external | ||
99 | access, use the ``WEBPORT`` parameter to open an address that connects | ||
100 | to the network, specifically the IP address that your NIC uses to | ||
101 | connect to the network. You can also bind to all IP addresses the | ||
102 | computer supports by using the shortcut "0.0.0.0:port". | ||
103 | |||
104 | The following example binds to all IP addresses on the host:: | ||
105 | |||
106 | $ source toaster start webport=0.0.0.0:8400 | ||
107 | |||
108 | This example binds to a specific IP address on the host's NIC:: | ||
109 | |||
110 | $ source toaster start webport=192.168.1.1:8400 | ||
111 | |||
112 | The Directory for Cloning Layers | ||
113 | ================================ | ||
114 | |||
115 | Toaster creates a ``_toaster_clones`` directory inside your Source | ||
116 | Directory (i.e. ``poky``) to clone any layers needed for your builds. | ||
117 | |||
118 | Alternatively, if you would like all of your Toaster related files and | ||
119 | directories to be in a particular location other than the default, you | ||
120 | can set the ``TOASTER_DIR`` environment variable, which takes precedence | ||
121 | over your current working directory. Setting this environment variable | ||
122 | causes Toaster to create and use ``$TOASTER_DIR./_toaster_clones``. | ||
123 | |||
124 | .. _toaster-the-build-directory: | ||
125 | |||
126 | The Build Directory | ||
127 | =================== | ||
128 | |||
129 | Toaster creates a build directory within your Source Directory (e.g. | ||
130 | ``poky``) to execute the builds. | ||
131 | |||
132 | Alternatively, if you would like all of your Toaster related files and | ||
133 | directories to be in a particular location, you can set the | ||
134 | ``TOASTER_DIR`` environment variable, which takes precedence over your | ||
135 | current working directory. Setting this environment variable causes | ||
136 | Toaster to use ``$TOASTER_DIR/build`` as the build directory. | ||
137 | |||
138 | .. _toaster-creating-a-django-super-user: | ||
139 | |||
140 | Creating a Django Superuser | ||
141 | =========================== | ||
142 | |||
143 | Toaster is built on the `Django | ||
144 | framework <https://www.djangoproject.com/>`__. Django provides an | ||
145 | administration interface you can use to edit Toaster configuration | ||
146 | parameters. | ||
147 | |||
148 | To access the Django administration interface, you must create a | ||
149 | superuser by following these steps: | ||
150 | |||
151 | #. If you used ``pip3``, which is recommended, to set up the Toaster | ||
152 | system dependencies, you need be sure the local user path is in your | ||
153 | ``PATH`` list. To append the pip3 local user path, use the following | ||
154 | command:: | ||
155 | |||
156 | $ export PATH=$PATH:$HOME/.local/bin | ||
157 | |||
158 | #. From the directory containing the Toaster database, which by default | ||
159 | is the :term:`Build Directory`, | ||
160 | invoke the ``createsuperuser`` command from ``manage.py``:: | ||
161 | |||
162 | $ cd ~/poky/build | ||
163 | $ ../bitbake/lib/toaster/manage.py createsuperuser | ||
164 | |||
165 | #. Django prompts you for the username, which you need to provide. | ||
166 | |||
167 | #. Django prompts you for an email address, which is optional. | ||
168 | |||
169 | #. Django prompts you for a password, which you must provide. | ||
170 | |||
171 | #. Django prompts you to re-enter your password for verification. | ||
172 | |||
173 | After completing these steps, the following confirmation message | ||
174 | appears:: | ||
175 | |||
176 | Superuser created successfully. | ||
177 | |||
178 | Creating a superuser allows you to access the Django administration | ||
179 | interface through a browser. The URL for this interface is the same as | ||
180 | the URL used for the Toaster instance with "/admin" on the end. For | ||
181 | example, if you are running Toaster locally, use the following URL:: | ||
182 | |||
183 | http://127.0.0.1:8000/admin | ||
184 | |||
185 | You can use the Django administration interface to set Toaster configuration | ||
186 | parameters such as the build directory, layer sources, default variable | ||
187 | values, and BitBake versions. | ||
188 | |||
189 | .. _toaster-setting-up-a-production-instance-of-toaster: | ||
190 | |||
191 | Setting Up a Production Instance of Toaster | ||
192 | =========================================== | ||
193 | |||
194 | You can use a production instance of Toaster to share the Toaster | ||
195 | instance with remote users, multiple users, or both. The production | ||
196 | instance is also the setup that can handle heavier loads on the web | ||
197 | service. Use the instructions in the following sections to set up | ||
198 | Toaster to run builds through the Toaster web interface. | ||
199 | |||
200 | .. _toaster-production-instance-requirements: | ||
201 | |||
202 | Requirements | ||
203 | ------------ | ||
204 | |||
205 | Be sure you meet the following requirements: | ||
206 | |||
207 | .. note:: | ||
208 | |||
209 | You must comply with all Apache, ``mod-wsgi``, and Mysql requirements. | ||
210 | |||
211 | - Have all the build requirements as described in the ":ref:`toaster-manual/toaster-manual-start:Preparing to | ||
212 | Use Toaster`" chapter. | ||
213 | |||
214 | - Have an Apache webserver. | ||
215 | |||
216 | - Have ``mod-wsgi`` for the Apache webserver. | ||
217 | |||
218 | - Use the Mysql database server. | ||
219 | |||
220 | - If you are using Ubuntu, run the following:: | ||
221 | |||
222 | $ sudo apt-get install apache2 libapache2-mod-wsgi-py3 mysql-server python3-pip libmysqlclient-dev | ||
223 | |||
224 | - If you are using Fedora or a RedHat distribution, run the | ||
225 | following:: | ||
226 | |||
227 | $ sudo dnf install httpd python3-mod_wsgi python3-pip mariadb-server mariadb-devel python3-devel | ||
228 | |||
229 | - If you are using openSUSE, run the following:: | ||
230 | |||
231 | $ sudo zypper install apache2 apache2-mod_wsgi-python3 python3-pip mariadb mariadb-client python3-devel | ||
232 | |||
233 | .. _toaster-installation-steps: | ||
234 | |||
235 | Installation | ||
236 | ------------ | ||
237 | |||
238 | Perform the following steps to install Toaster: | ||
239 | |||
240 | #. Create toaster user and set its home directory to | ||
241 | ``/var/www/toaster``:: | ||
242 | |||
243 | $ sudo /usr/sbin/useradd toaster -md /var/www/toaster -s /bin/false | ||
244 | $ sudo su - toaster -s /bin/bash | ||
245 | |||
246 | #. Checkout a copy of ``poky`` into the web server directory. You will | ||
247 | be using ``/var/www/toaster``:: | ||
248 | |||
249 | $ git clone git://git.yoctoproject.org/poky | ||
250 | $ git checkout &DISTRO_NAME_NO_CAP; | ||
251 | |||
252 | #. Install Toaster dependencies using the --user flag which keeps the | ||
253 | Python packages isolated from your system-provided packages:: | ||
254 | |||
255 | $ cd /var/www/toaster/ | ||
256 | $ pip3 install --user -r ./poky/bitbake/toaster-requirements.txt | ||
257 | $ pip3 install --user mysqlclient | ||
258 | |||
259 | .. note:: | ||
260 | |||
261 | Isolating these packages is not required but is recommended. | ||
262 | Alternatively, you can use your operating system's package | ||
263 | manager to install the packages. | ||
264 | |||
265 | #. Configure Toaster by editing | ||
266 | ``/var/www/toaster/poky/bitbake/lib/toaster/toastermain/settings.py`` | ||
267 | as follows: | ||
268 | |||
269 | - Edit the | ||
270 | `DATABASES <https://docs.djangoproject.com/en/2.2/ref/settings/#databases>`__ | ||
271 | settings: | ||
272 | |||
273 | .. code-block:: python | ||
274 | |||
275 | DATABASES = { | ||
276 | 'default': { | ||
277 | 'ENGINE': 'django.db.backends.mysql', | ||
278 | 'NAME': 'toaster_data', | ||
279 | 'USER': 'toaster', | ||
280 | 'PASSWORD': 'yourpasswordhere', | ||
281 | 'HOST': 'localhost', | ||
282 | 'PORT': '3306', | ||
283 | } | ||
284 | } | ||
285 | |||
286 | - Edit the | ||
287 | `SECRET_KEY <https://docs.djangoproject.com/en/2.2/ref/settings/#std:setting-SECRET_KEY>`__: | ||
288 | |||
289 | .. code-block:: python | ||
290 | |||
291 | SECRET_KEY = 'your_secret_key' | ||
292 | |||
293 | - Edit the | ||
294 | `STATIC_ROOT <https://docs.djangoproject.com/en/2.2/ref/settings/#std:setting-STATIC_ROOT>`__: | ||
295 | |||
296 | .. code-block:: python | ||
297 | |||
298 | STATIC_ROOT = '/var/www/toaster/static_files/' | ||
299 | |||
300 | #. Add the database and user to the ``mysql`` server defined earlier:: | ||
301 | |||
302 | $ mysql -u root -p | ||
303 | mysql> CREATE DATABASE toaster_data; | ||
304 | mysql> CREATE USER 'toaster'@'localhost' identified by 'yourpasswordhere'; | ||
305 | mysql> GRANT all on toaster_data.\* to 'toaster'@'localhost'; | ||
306 | mysql> quit | ||
307 | |||
308 | #. Get Toaster to create the database schema, default data, and gather | ||
309 | the statically-served files:: | ||
310 | |||
311 | $ cd /var/www/toaster/poky/ | ||
312 | $ ./bitbake/lib/toaster/manage.py migrate | ||
313 | $ TOASTER_DIR=`pwd\` TEMPLATECONF='poky' \ | ||
314 | ./bitbake/lib/toaster/manage.py checksettings | ||
315 | $ ./bitbake/lib/toaster/manage.py collectstatic | ||
316 | |||
317 | |||
318 | In the previous | ||
319 | example, from the ``poky`` directory, the ``migrate`` command | ||
320 | ensures the database schema changes have propagated correctly (i.e. | ||
321 | migrations). The next line sets the Toaster root directory | ||
322 | ``TOASTER_DIR`` and the location of the Toaster configuration file | ||
323 | ``TOASTER_CONF``, which is relative to ``TOASTER_DIR``. The | ||
324 | ``TEMPLATECONF`` value reflects the contents of | ||
325 | ``poky/.templateconf``, and by default, should include the string | ||
326 | "poky". For more information on the Toaster configuration file, see | ||
327 | the ":ref:`toaster-manual/toaster-manual-reference:Configuring Toaster`" section. | ||
328 | |||
329 | This line also runs the ``checksettings`` command, which configures | ||
330 | the location of the Toaster :term:`Build Directory`. | ||
331 | The Toaster | ||
332 | root directory ``TOASTER_DIR`` determines where the Toaster build | ||
333 | directory is created on the file system. In the example above, | ||
334 | ``TOASTER_DIR`` is set as follows:: | ||
335 | |||
336 | /var/www/toaster/poky | ||
337 | |||
338 | |||
339 | This setting causes the Toaster build directory to be:: | ||
340 | |||
341 | /var/www/toaster/poky/build | ||
342 | |||
343 | Finally, the ``collectstatic`` command is a Django framework command | ||
344 | that collects all the statically served files into a designated | ||
345 | directory to be served up by the Apache web server as defined by | ||
346 | ``STATIC_ROOT``. | ||
347 | |||
348 | #. Test and/or use the Mysql integration with Toaster's Django web | ||
349 | server. At this point, you can start up the normal Toaster Django | ||
350 | web server with the Toaster database in Mysql. You can use this web | ||
351 | server to confirm that the database migration and data population | ||
352 | from the Layer Index is complete. | ||
353 | |||
354 | To start the default Toaster Django web server with the Toaster | ||
355 | database now in Mysql, use the standard start commands:: | ||
356 | |||
357 | $ source oe-init-build-env | ||
358 | $ source toaster start | ||
359 | |||
360 | Additionally, if Django is sufficient for your requirements, you can use | ||
361 | it for your release system and migrate later to Apache as your | ||
362 | requirements change. | ||
363 | |||
364 | #. Add an Apache configuration file for Toaster to your Apache web | ||
365 | server's configuration directory. If you are using Ubuntu or Debian, | ||
366 | put the file here:: | ||
367 | |||
368 | /etc/apache2/conf-available/toaster.conf | ||
369 | |||
370 | |||
371 | If you are using Fedora or RedHat, put it here:: | ||
372 | |||
373 | /etc/httpd/conf.d/toaster.conf | ||
374 | |||
375 | If you are using OpenSUSE, put it here:: | ||
376 | |||
377 | /etc/apache2/conf.d/toaster.conf | ||
378 | |||
379 | Following is a sample Apache configuration for Toaster you can follow: | ||
380 | |||
381 | .. code-block:: apache | ||
382 | |||
383 | Alias /static /var/www/toaster/static_files | ||
384 | <Directory /var/www/toaster/static_files> | ||
385 | <IfModule mod_access_compat.c> | ||
386 | Order allow,deny | ||
387 | Allow from all | ||
388 | </IfModule> | ||
389 | <IfModule !mod_access_compat.c> | ||
390 | Require all granted | ||
391 | </IfModule> | ||
392 | </Directory> | ||
393 | |||
394 | <Directory /var/www/toaster/poky/bitbake/lib/toaster/toastermain> | ||
395 | <Files "wsgi.py"> | ||
396 | Require all granted | ||
397 | </Files> | ||
398 | </Directory> | ||
399 | |||
400 | WSGIDaemonProcess toaster_wsgi python-path=/var/www/toaster/poky/bitbake/lib/toaster:/var/www/toaster/.local/lib/python3.4/site-packages | ||
401 | WSGIScriptAlias / "/var/www/toaster/poky/bitbake/lib/toaster/toastermain/wsgi.py" | ||
402 | <Location /> | ||
403 | WSGIProcessGroup toaster_wsgi | ||
404 | </Location> | ||
405 | |||
406 | |||
407 | If you are using Ubuntu or Debian, you will need to enable the config and | ||
408 | module for Apache:: | ||
409 | |||
410 | $ sudo a2enmod wsgi | ||
411 | $ sudo a2enconf toaster | ||
412 | $ chmod +x bitbake/lib/toaster/toastermain/wsgi.py | ||
413 | |||
414 | Finally, restart Apache to make sure all new configuration is loaded. For Ubuntu, | ||
415 | Debian, and OpenSUSE use:: | ||
416 | |||
417 | $ sudo service apache2 restart | ||
418 | |||
419 | For Fedora and RedHat use:: | ||
420 | |||
421 | $ sudo service httpd restart | ||
422 | |||
423 | #. Prepare the systemd service to run Toaster builds. Here is a sample | ||
424 | configuration file for the service: | ||
425 | |||
426 | .. code-block:: ini | ||
427 | |||
428 | [Unit] | ||
429 | Description=Toaster runbuilds | ||
430 | |||
431 | [Service] | ||
432 | Type=forking User=toaster | ||
433 | ExecStart=/usr/bin/screen -d -m -S runbuilds /var/www/toaster/poky/bitbake/lib/toaster/runbuilds-service.sh start | ||
434 | ExecStop=/usr/bin/screen -S runbuilds -X quit | ||
435 | WorkingDirectory=/var/www/toaster/poky | ||
436 | |||
437 | [Install] | ||
438 | WantedBy=multi-user.target | ||
439 | |||
440 | |||
441 | Prepare the ``runbuilds-service.sh`` script that you need to place in the | ||
442 | ``/var/www/toaster/poky/bitbake/lib/toaster/`` directory by setting | ||
443 | up executable permissions:: | ||
444 | |||
445 | #!/bin/bash | ||
446 | |||
447 | #export http_proxy=http://proxy.host.com:8080 | ||
448 | #export https_proxy=http://proxy.host.com:8080 | ||
449 | #export GIT_PROXY_COMMAND=$HOME/bin/gitproxy | ||
450 | cd ~/poky/ | ||
451 | source ./oe-init-build-env build | ||
452 | source ../bitbake/bin/toaster $1 noweb | ||
453 | [ "$1" == 'start' ] && /bin/bash | ||
454 | |||
455 | #. Run the service:: | ||
456 | |||
457 | $ sudo service runbuilds start | ||
458 | |||
459 | Since the service is running in a detached screen session, you can | ||
460 | attach to it using this command:: | ||
461 | |||
462 | $ sudo su - toaster | ||
463 | $ screen -rS runbuilds | ||
464 | |||
465 | You can detach from the service again using "Ctrl-a" followed by "d" key | ||
466 | combination. | ||
467 | |||
468 | You can now open up a browser and start using Toaster. | ||
469 | |||
470 | Using the Toaster Web Interface | ||
471 | =============================== | ||
472 | |||
473 | The Toaster web interface allows you to do the following: | ||
474 | |||
475 | - Browse published layers in the `OpenEmbedded Layer | ||
476 | Index <http://layers.openembedded.org>`__ that are available for your | ||
477 | selected version of the build system. | ||
478 | |||
479 | - Import your own layers for building. | ||
480 | |||
481 | - Add and remove layers from your configuration. | ||
482 | |||
483 | - Set configuration variables. | ||
484 | |||
485 | - Select a target or multiple targets to build. | ||
486 | |||
487 | - Start your builds. | ||
488 | |||
489 | - See what was built (recipes and packages) and what packages were | ||
490 | installed into your final image. | ||
491 | |||
492 | - Browse the directory structure of your image. | ||
493 | |||
494 | - See the value of all variables in your build configuration, and which | ||
495 | files set each value. | ||
496 | |||
497 | - Examine error, warning and trace messages to aid in debugging. | ||
498 | |||
499 | - See information about the BitBake tasks executed and reused during | ||
500 | your build, including those that used shared state. | ||
501 | |||
502 | - See dependency relationships between recipes, packages and tasks. | ||
503 | |||
504 | - See performance information such as build time, task time, CPU usage, | ||
505 | and disk I/O. | ||
506 | |||
507 | .. _web-interface-videos: | ||
508 | |||
509 | Toaster Web Interface Videos | ||
510 | ---------------------------- | ||
511 | |||
512 | Following are several videos that show how to use the Toaster GUI: | ||
513 | |||
514 | - *Build Configuration:* This | ||
515 | `video <https://www.youtube.com/watch?v=qYgDZ8YzV6w>`__ overviews and | ||
516 | demonstrates build configuration for Toaster. | ||
517 | |||
518 | - *Build Custom Layers:* This | ||
519 | `video <https://www.youtube.com/watch?v=QJzaE_XjX5c>`__ shows you how | ||
520 | to build custom layers that are used with Toaster. | ||
521 | |||
522 | - *Toaster Homepage and Table Controls:* This | ||
523 | `video <https://www.youtube.com/watch?v=QEARDnrR1Xw>`__ goes over the | ||
524 | Toaster entry page, and provides an overview of the data manipulation | ||
525 | capabilities of Toaster, which include search, sorting and filtering | ||
526 | by different criteria. | ||
527 | |||
528 | - *Build Dashboard:* This | ||
529 | `video <https://www.youtube.com/watch?v=KKqHYcnp2gE>`__ shows you the | ||
530 | build dashboard, a page providing an overview of the information | ||
531 | available for a selected build. | ||
532 | |||
533 | - *Image Information:* This | ||
534 | `video <https://www.youtube.com/watch?v=XqYGFsmA0Rw>`__ walks through | ||
535 | the information Toaster provides about images: packages installed and | ||
536 | root file system. | ||
537 | |||
538 | - *Configuration:* This | ||
539 | `video <https://www.youtube.com/watch?v=UW-j-T2TzIg>`__ provides | ||
540 | Toaster build configuration information. | ||
541 | |||
542 | - *Tasks:* This `video <https://www.youtube.com/watch?v=D4-9vGSxQtw>`__ | ||
543 | shows the information Toaster provides about the tasks run by the | ||
544 | build system. | ||
545 | |||
546 | - *Recipes and Packages Built:* This | ||
547 | `video <https://www.youtube.com/watch?v=x-6dx4huNnw>`__ shows the | ||
548 | information Toaster provides about recipes and packages built. | ||
549 | |||
550 | - *Performance Data:* This | ||
551 | `video <https://www.youtube.com/watch?v=qWGMrJoqusQ>`__ shows the | ||
552 | build performance data provided by Toaster. | ||
553 | |||
554 | .. _a-note-on-the-local-yocto-project-release: | ||
555 | |||
556 | Additional Information About the Local Yocto Project Release | ||
557 | ------------------------------------------------------------ | ||
558 | |||
559 | This section only applies if you have set up Toaster for local | ||
560 | development, as explained in the | ||
561 | ":ref:`toaster-manual/toaster-manual-setup-and-use:starting toaster for local development`" | ||
562 | section. | ||
563 | |||
564 | When you create a project in Toaster, you will be asked to provide a | ||
565 | name and to select a Yocto Project release. One of the release options | ||
566 | you will find is called "Local Yocto Project". | ||
567 | |||
568 | .. image:: figures/new-project.png | ||
569 | :align: center | ||
570 | :scale: 75% | ||
571 | |||
572 | When you select the "Local Yocto Project" release, Toaster will run your | ||
573 | builds using the local Yocto Project clone you have in your computer: | ||
574 | the same clone you are using to run Toaster. Unless you manually update | ||
575 | this clone, your builds will always use the same Git revision. | ||
576 | |||
577 | If you select any of the other release options, Toaster will fetch the | ||
578 | tip of your selected release from the upstream `Yocto Project | ||
579 | repository <https://git.yoctoproject.org>`__ every time you run a build. | ||
580 | Fetching this tip effectively means that if your selected release is | ||
581 | updated upstream, the Git revision you are using for your builds will | ||
582 | change. If you are doing development locally, you might not want this | ||
583 | change to happen. In that case, the "Local Yocto Project" release might | ||
584 | be the right choice. | ||
585 | |||
586 | However, the "Local Yocto Project" release will not provide you with any | ||
587 | compatible layers, other than the three core layers that come with the | ||
588 | Yocto Project: | ||
589 | |||
590 | - `openembedded-core <http://layers.openembedded.org/layerindex/branch/master/layer/openembedded-core/>`__ | ||
591 | |||
592 | - `meta-poky <http://layers.openembedded.org/layerindex/branch/master/layer/meta-poky/>`__ | ||
593 | |||
594 | - `meta-yocto-bsp <http://layers.openembedded.org/layerindex/branch/master/layer/meta-yocto-bsp/>`__ | ||
595 | |||
596 | .. image:: figures/compatible-layers.png | ||
597 | :align: center | ||
598 | :scale: 75% | ||
599 | |||
600 | If you want to build any other layers, you will need to manually import | ||
601 | them into your Toaster project, using the "Import layer" page. | ||
602 | |||
603 | .. image:: figures/import-layer.png | ||
604 | :align: center | ||
605 | :scale: 75% | ||
606 | |||
607 | .. _toaster-web-interface-preferred-version: | ||
608 | |||
609 | Building a Specific Recipe Given Multiple Versions | ||
610 | -------------------------------------------------- | ||
611 | |||
612 | Occasionally, a layer might provide more than one version of the same | ||
613 | recipe. For example, the ``openembedded-core`` layer provides two | ||
614 | versions of the ``bash`` recipe (i.e. 3.2.48 and 4.3.30-r0) and two | ||
615 | versions of the ``which`` recipe (i.e. 2.21 and 2.18). The following | ||
616 | figure shows this exact scenario: | ||
617 | |||
618 | .. image:: figures/bash-oecore.png | ||
619 | :align: center | ||
620 | :scale: 75% | ||
621 | |||
622 | By default, the OpenEmbedded build system builds one of the two recipes. | ||
623 | For the ``bash`` case, version 4.3.30-r0 is built by default. | ||
624 | Unfortunately, Toaster as it exists, is not able to override the default | ||
625 | recipe version. If you would like to build bash 3.2.48, you need to set | ||
626 | the | ||
627 | :term:`PREFERRED_VERSION` | ||
628 | variable. You can do so from Toaster, using the "Add variable" form, | ||
629 | which is available in the "BitBake variables" page of the project | ||
630 | configuration section as shown in the following screen: | ||
631 | |||
632 | .. image:: figures/add-variable.png | ||
633 | :align: center | ||
634 | :scale: 75% | ||
635 | |||
636 | To specify ``bash`` 3.2.48 as the version to build, enter | ||
637 | "PREFERRED_VERSION_bash" in the "Variable" field, and "3.2.48" in the | ||
638 | "Value" field. Next, click the "Add variable" button: | ||
639 | |||
640 | .. image:: figures/set-variable.png | ||
641 | :align: center | ||
642 | :scale: 75% | ||
643 | |||
644 | After clicking the "Add variable" button, the settings for | ||
645 | ``PREFERRED_VERSION`` are added to the bottom of the BitBake variables | ||
646 | list. With these settings, the OpenEmbedded build system builds the | ||
647 | desired version of the recipe rather than the default version: | ||
648 | |||
649 | .. image:: figures/variable-added.png | ||
650 | :align: center | ||
651 | :scale: 75% | ||
diff --git a/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/documentation/toaster-manual/toaster-manual-setup-and-use.xml index b4caebbe0f..f555745923 100644 --- a/documentation/toaster-manual/toaster-manual-setup-and-use.xml +++ b/documentation/toaster-manual/toaster-manual-setup-and-use.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <chapter id='toaster-manual-setup-and-use'> | 6 | <chapter id='toaster-manual-setup-and-use'> |
6 | 7 | ||
@@ -69,17 +70,17 @@ | |||
69 | web server. This is useful for the following: | 70 | web server. This is useful for the following: |
70 | <itemizedlist> | 71 | <itemizedlist> |
71 | <listitem><para> | 72 | <listitem><para> |
72 | Capturing a command-line build’s statistics into | 73 | Capturing a command-line build's statistics into |
73 | the Toaster database for examination later. | 74 | the Toaster database for examination later. |
74 | </para></listitem> | 75 | </para></listitem> |
75 | <listitem><para> | 76 | <listitem><para> |
76 | Capturing a command-line build’s statistics when | 77 | Capturing a command-line build's statistics when |
77 | the Toaster server is already running. | 78 | the Toaster server is already running. |
78 | </para></listitem> | 79 | </para></listitem> |
79 | <listitem><para> | 80 | <listitem><para> |
80 | Having one instance of the Toaster web server | 81 | Having one instance of the Toaster web server |
81 | track and capture multiple command-line builds, | 82 | track and capture multiple command-line builds, |
82 | where each build is started in its own “noweb” | 83 | where each build is started in its own "noweb" |
83 | Toaster environment. | 84 | Toaster environment. |
84 | </para></listitem> | 85 | </para></listitem> |
85 | </itemizedlist> | 86 | </itemizedlist> |
@@ -91,7 +92,7 @@ | |||
91 | minutes to ensure the complete transfer of its BitBake build | 92 | minutes to ensure the complete transfer of its BitBake build |
92 | statistics to the Toaster database. | 93 | statistics to the Toaster database. |
93 | If you have a separate Toaster web server instance running, you | 94 | If you have a separate Toaster web server instance running, you |
94 | can watch this command-line build’s progress and examine the | 95 | can watch this command-line build's progress and examine the |
95 | results as soon as they are posted: | 96 | results as soon as they are posted: |
96 | <literallayout class='monospaced'> | 97 | <literallayout class='monospaced'> |
97 | $ source toaster start noweb | 98 | $ source toaster start noweb |
@@ -106,7 +107,7 @@ | |||
106 | 107 | ||
107 | <para> | 108 | <para> |
108 | You can start a Toaster environment with the | 109 | You can start a Toaster environment with the |
109 | “New Projects” feature disabled. | 110 | "New Projects" feature disabled. |
110 | Doing so is useful for the following: | 111 | Doing so is useful for the following: |
111 | <itemizedlist> | 112 | <itemizedlist> |
112 | <listitem><para> | 113 | <listitem><para> |
@@ -469,7 +470,7 @@ | |||
469 | <filename>STATIC_ROOT</filename>. | 470 | <filename>STATIC_ROOT</filename>. |
470 | </para></listitem> | 471 | </para></listitem> |
471 | <listitem><para> | 472 | <listitem><para> |
472 | Test and/or use the Mysql integration with Toaster’s | 473 | Test and/or use the Mysql integration with Toaster's |
473 | Django web server. | 474 | Django web server. |
474 | At this point, you can start up the normal Toaster | 475 | At this point, you can start up the normal Toaster |
475 | Django web server with the Toaster database in Mysql. | 476 | Django web server with the Toaster database in Mysql. |
diff --git a/documentation/toaster-manual/toaster-manual-start.rst b/documentation/toaster-manual/toaster-manual-start.rst new file mode 100644 index 0000000000..2d612b8938 --- /dev/null +++ b/documentation/toaster-manual/toaster-manual-start.rst | |||
@@ -0,0 +1,57 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | .. Set default pygments highlighting to shell for this document | ||
3 | .. highlight:: shell | ||
4 | |||
5 | ************************ | ||
6 | Preparing to Use Toaster | ||
7 | ************************ | ||
8 | |||
9 | This chapter describes how you need to prepare your system in order to | ||
10 | use Toaster. | ||
11 | |||
12 | .. _toaster-setting-up-the-basic-system-requirements: | ||
13 | |||
14 | Setting Up the Basic System Requirements | ||
15 | ======================================== | ||
16 | |||
17 | Before you can use Toaster, you need to first set up your build system | ||
18 | to run the Yocto Project. To do this, follow the instructions in the | ||
19 | ":ref:`dev-manual/dev-manual-start:preparing the build host`" section of | ||
20 | the Yocto Project Development Tasks Manual. For Ubuntu/Debian, you might | ||
21 | also need to do an additional install of pip3. :: | ||
22 | |||
23 | $ sudo apt-get install python3-pip | ||
24 | |||
25 | .. _toaster-establishing-toaster-system-dependencies: | ||
26 | |||
27 | Establishing Toaster System Dependencies | ||
28 | ======================================== | ||
29 | |||
30 | Toaster requires extra Python dependencies in order to run. A Toaster | ||
31 | requirements file named ``toaster-requirements.txt`` defines the Python | ||
32 | dependencies. The requirements file is located in the ``bitbake`` | ||
33 | directory, which is located in the root directory of the | ||
34 | :term:`Source Directory` (e.g. | ||
35 | ``poky/bitbake/toaster-requirements.txt``). The dependencies appear in a | ||
36 | ``pip``, install-compatible format. | ||
37 | |||
38 | .. _toaster-load-packages: | ||
39 | |||
40 | Install Toaster Packages | ||
41 | ------------------------ | ||
42 | |||
43 | You need to install the packages that Toaster requires. Use this | ||
44 | command:: | ||
45 | |||
46 | $ pip3 install --user -r bitbake/toaster-requirements.txt | ||
47 | |||
48 | The previous command installs the necessary Toaster modules into a local | ||
49 | python 3 cache in your ``$HOME`` directory. The caches is actually | ||
50 | located in ``$HOME/.local``. To see what packages have been installed | ||
51 | into your ``$HOME`` directory, do the following:: | ||
52 | |||
53 | $ pip3 list installed --local | ||
54 | |||
55 | If you need to remove something, the following works:: | ||
56 | |||
57 | $ pip3 uninstall PackageNameToUninstall | ||
diff --git a/documentation/toaster-manual/toaster-manual-start.xml b/documentation/toaster-manual/toaster-manual-start.xml index fc187ecd5e..8a857006e5 100644 --- a/documentation/toaster-manual/toaster-manual-start.xml +++ b/documentation/toaster-manual/toaster-manual-start.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <chapter id='toaster-manual-start'> | 6 | <chapter id='toaster-manual-start'> |
6 | 7 | ||
diff --git a/documentation/toaster-manual/toaster-manual-style.css b/documentation/toaster-manual/toaster-manual-style.css index 6d6b9fb65d..a7f430df05 100644 --- a/documentation/toaster-manual/toaster-manual-style.css +++ b/documentation/toaster-manual/toaster-manual-style.css | |||
@@ -1,4 +1,7 @@ | |||
1 | /* | 1 | /* |
2 | |||
3 | SPDX-License-Identifier: CC-BY-2.0-UK | ||
4 | |||
2 | Generic XHTML / DocBook XHTML CSS Stylesheet. | 5 | Generic XHTML / DocBook XHTML CSS Stylesheet. |
3 | 6 | ||
4 | Browser wrangling and typographic design by | 7 | Browser wrangling and typographic design by |
diff --git a/documentation/toaster-manual/toaster-manual.rst b/documentation/toaster-manual/toaster-manual.rst new file mode 100644 index 0000000000..f6f59411b6 --- /dev/null +++ b/documentation/toaster-manual/toaster-manual.rst | |||
@@ -0,0 +1,19 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | =================== | ||
4 | Toaster User Manual | ||
5 | =================== | ||
6 | |||
7 | | | ||
8 | |||
9 | .. toctree:: | ||
10 | :caption: Table of Contents | ||
11 | :numbered: | ||
12 | |||
13 | toaster-manual-intro | ||
14 | toaster-manual-start | ||
15 | toaster-manual-setup-and-use | ||
16 | toaster-manual-reference | ||
17 | history | ||
18 | |||
19 | .. include:: /boilerplate.rst | ||
diff --git a/documentation/toaster-manual/toaster-manual.xml b/documentation/toaster-manual/toaster-manual.xml index 03db6bed3a..136b4df964 100755 --- a/documentation/toaster-manual/toaster-manual.xml +++ b/documentation/toaster-manual/toaster-manual.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <book id='toaster-manual' lang='en' | 6 | <book id='toaster-manual' lang='en' |
6 | xmlns:xi="http://www.w3.org/2003/XInclude" | 7 | xmlns:xi="http://www.w3.org/2003/XInclude" |
@@ -82,28 +83,8 @@ | |||
82 | </revision> | 83 | </revision> |
83 | <revision> | 84 | <revision> |
84 | <revnumber>3.1</revnumber> | 85 | <revnumber>3.1</revnumber> |
85 | <date>April 2020</date> | ||
86 | <revremark>Released with the Yocto Project 3.1 Release.</revremark> | ||
87 | </revision> | ||
88 | <revision> | ||
89 | <revnumber>3.1.1</revnumber> | ||
90 | <date>June 2020</date> | ||
91 | <revremark>Released with the Yocto Project 3.1.1 Release.</revremark> | ||
92 | </revision> | ||
93 | <revision> | ||
94 | <revnumber>3.1.2</revnumber> | ||
95 | <date>August 2020</date> | ||
96 | <revremark>Released with the Yocto Project 3.1.2 Release.</revremark> | ||
97 | </revision> | ||
98 | <revision> | ||
99 | <revnumber>3.1.3</revnumber> | ||
100 | <date>October 2020</date> | ||
101 | <revremark>Released with the Yocto Project 3.1.3 Release.</revremark> | ||
102 | </revision> | ||
103 | <revision> | ||
104 | <revnumber>3.1.4</revnumber> | ||
105 | <date>&REL_MONTH_YEAR;</date> | 86 | <date>&REL_MONTH_YEAR;</date> |
106 | <revremark>Released with the Yocto Project 3.1.4 Release.</revremark> | 87 | <revremark>Released with the Yocto Project 3.1 Release.</revremark> |
107 | </revision> | 88 | </revision> |
108 | </revhistory> | 89 | </revhistory> |
109 | 90 | ||