1.. _yocto_project_core_components:
2
3=============================
4Yocto Project Core Components
5=============================
6
7The BitBake task executor together with various types of configuration files
8form the OpenEmbedded-Core (OE-Core). This section overviews these components
9by describing their use and how they interact.
10
11BitBake handles the parsing and execution of the data files. The data
12itself is of various types:
13
14-  *Recipes:* Provides details about particular pieces of software.
15
16-  *Class Data:* Abstracts common build information (e.g. how to build a
17   Linux kernel).
18
19-  *Configuration Data:* Defines machine-specific settings, policy
20   decisions, and so forth. Configuration data acts as the glue to bind
21   everything together.
22
23BitBake knows how to combine multiple data sources together and refers
24to each data source as a layer.
25
26Here are some brief details on these core components.
27
28.. _bitbake_section:
29
30BitBake
31*******
32
33BitBake is the tool at the heart of the OpenEmbedded Build System and is
34responsible for parsing the Metadata, generating a list of tasks from it, and
35then executing those tasks.
36
37This section briefly introduces BitBake. If you want more information on
38BitBake, see the `BitBake User Manual <https://docs.yoctoproject.org/bitbake/2.
398/index.html>`_.
40
41To see a list of the options BitBake supports, use either of the
42following commands::
43
44   $ bitbake -h
45   $ bitbake --help
46
47The most common usage for BitBake is ``bitbake recipename``, where
48``recipename`` is the name of the recipe you want to build (referred
49to as the "target"). The target often equates to the first part of a
50recipe's filename (e.g. "foo" for a recipe named ``foo_1.3.0-r0.bb``).
51So, to process the ``matchbox-desktop_1.2.3.bb`` recipe file, you might
52type the following::
53
54   $ bitbake matchbox-desktop
55
56Several different versions of ``matchbox-desktop`` might exist. BitBake chooses
57the one selected by the distribution configuration. You can get more details
58about how BitBake chooses between different target versions and providers in the
59"`Preferences <https://docs.yoctoproject.org/bitbake/2.8/bitbake-user-manual/
60bitbake-user-manual-execution.html#preferences>`_" section of the BitBake User
61Manual.
62
63BitBake also tries to execute any dependent tasks first. So for example,
64before building ``matchbox-desktop``, BitBake would build a cross
65compiler and ``glibc`` if they had not already been built.
66
67A useful BitBake option to consider is the ``-k`` or ``--continue``
68option. This option instructs BitBake to try and continue processing the
69job as long as possible even after encountering an error. When an error
70occurs, the target that failed and those that depend on it cannot be
71remade. However, when you use this option other dependencies can still
72be processed.
73
74.. _recipes_section:
75
76Recipes
77*******
78
79Files that have the ``.bb`` suffix are "recipes" files. In general, a
80recipe contains information about a single piece of software. This
81information includes the location from which to download the unaltered
82source, any source patches to be applied to that source (if needed),
83which special configuration options to apply, how to compile the source
84files, and how to package the compiled output.
85
86The term "package" is sometimes used to refer to recipes. However, since
87the word "package" is used for the packaged output from the OpenEmbedded
88build system (i.e. ``.ipk`` or ``.deb`` files), this document avoids
89using the term "package" when referring to recipes.
90
91
92.. _classes_section:
93
94Classes
95*******
96
97Class files (``.bbclass``) contain information that is useful to share
98between recipes files. An example is the autotools* class,
99which contains common settings for any application that is built with
100the `GNU Autotools <https://en.wikipedia.org/wiki/GNU_Autotools>`.
101The "`Classes <https://docs.yoctoproject.org/ref-manual/classes.
102html#classes>`_" chapter in the Yocto Project
103Reference Manual provides details about classes and how to use them.
104
105
106.. _configurations_section:
107
108Configurations
109**************
110
111The configuration files (``.conf``) define various configuration
112variables that govern the OpenEmbedded build process. These files fall
113into several areas that define machine configuration options,
114distribution configuration options, compiler tuning options, general
115common configuration options, and user configuration options in
116``conf/local.conf``, which is found in the `Build Directory <https://docs.
117yoctoproject.org/ref-manual/terms.html#term-Build-Directory>`_.
118
119.. _layers_section:
120
121Layers
122******
123
124Layers are repositories that contain related metadata (i.e. sets of
125instructions) that tell the OpenEmbedded build system how to build a
126target. `The yocto project layer model <https://docs.yoctoproject.org/
127overview-manual/yp-intro.html#the-yocto-project-layer-model>`_
128facilitates collaboration, sharing, customization, and reuse within the
129Yocto Project development environment. Layers logically separate
130information for your project. For example, you can use a layer to hold
131all the configurations for a particular piece of hardware. Isolating
132hardware-specific configurations allows you to share other metadata by
133using a different layer where that metadata might be common across
134several pieces of hardware.
135
136There are many layers working in the Yocto Project development environment. The
137`Yocto Project Compatible Layer Index <https://www.yoctoproject.org/development/
138yocto-project-compatible-layers/>`_ and `OpenEmbedded Layer Index <https://
139layers.openembedded.org/layerindex/branch/master/layers/>`_ both contain layers
140from
141which you can use or leverage.
142
143By convention, layers in the Yocto Project follow a specific form. Conforming
144to a known structure allows BitBake to make assumptions during builds on where
145to find types of metadata. You can find procedures and learn about tools (i.e.
146``bitbake-layers``) for creating layers suitable for the Yocto Project in the
147"`understanding and creating layers <https://docs.yoctoproject.org/dev-manual/
148layers.html#understanding-and-creating-layers>`_" section of the
149Yocto Project Development Tasks Manual.
150