blob: a324744b7d3f1ba1674ec2872ef8affb804256bd [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
3************
4Introduction
5************
6
7Toaster is a web interface to the Yocto Project's
8:term:`OpenEmbedded Build System`. The interface
9enables you to configure and run your builds. Information about builds
10is collected and stored in a database. You can use Toaster to configure
11and start builds on multiple remote build servers.
12
Andrew Geisslerc9f78652020-09-18 14:11:35 -050013Toaster Features
14================
15
16Toaster allows you to configure and run builds, and it provides
17extensive information about the build process.
18
19- *Configure and Run Builds:* You can use the Toaster web interface to
20 configure and start your builds. Builds started using the Toaster web
21 interface are organized into projects. When you create a project, you
22 are asked to select a release, or version of the build system you
23 want to use for the project builds. As shipped, Toaster supports
24 Yocto Project releases 1.8 and beyond. With the Toaster web
25 interface, you can:
26
27 - Browse layers listed in the various
Andrew Geissler09209ee2020-12-13 08:44:15 -060028 :ref:`layer sources <toaster-manual/reference:layer source>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050029 that are available in your project (e.g. the OpenEmbedded Layer Index at
Andrew Geisslerd1e89492021-02-12 15:35:20 -060030 :oe_layerindex:`/`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -050031
32 - Browse images, recipes, and machines provided by those layers.
33
34 - Import your own layers for building.
35
36 - Add and remove layers from your configuration.
37
38 - Set configuration variables.
39
40 - Select a target or multiple targets to build.
41
42 - Start your builds.
43
44 Toaster also allows you to configure and run your builds from the
45 command line, and switch between the command line and the web
46 interface at any time. Builds started from the command line appear
47 within a special Toaster project called "Command line builds".
48
49- *Information About the Build Process:* Toaster also records extensive
50 information about your builds. Toaster collects data for builds you
51 start from the web interface and from the command line as long as
52 Toaster is running.
53
54 .. note::
55
56 You must start Toaster before the build or it will not collect
57 build data.
58
59 With Toaster you can:
60
61 - See what was built (recipes and packages) and what packages were
62 installed into your final image.
63
64 - Browse the directory structure of your image.
65
66 - See the value of all variables in your build configuration, and
67 which files set each value.
68
69 - Examine error, warning, and trace messages to aid in debugging.
70
71 - See information about the BitBake tasks executed and reused during
72 your build, including those that used shared state.
73
74 - See dependency relationships between recipes, packages, and tasks.
75
76 - See performance information such as build time, task time, CPU
77 usage, and disk I/O.
78
79For an overview of Toaster shipped with the Yocto Project &DISTRO;
80Release, see the "`Toaster - Yocto Project
812.2 <https://youtu.be/BlXdOYLgPxA>`__" video.
82
Andrew Geisslerc9f78652020-09-18 14:11:35 -050083Installation Options
84====================
85
86You can set Toaster up to run as a local instance or as a shared hosted
87service.
88
89When Toaster is set up as a local instance, all the components reside on
90a single build host. Fundamentally, a local instance of Toaster is
91suited for a single user developing on a single build host.
92
93.. image:: figures/simple-configuration.png
94 :align: center
Andrew Geisslerd5838332022-05-27 11:33:10 -050095 :width: 70%
Andrew Geisslerc9f78652020-09-18 14:11:35 -050096
97Toaster as a hosted service is suited for multiple users developing
98across several build hosts. When Toaster is set up as a hosted service,
99its components can be spread across several machines:
100
101.. image:: figures/hosted-service.png
102 :align: center
Andrew Geisslerd5838332022-05-27 11:33:10 -0500103 :width: 50%