summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/technical-details.xml
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-01-10 12:35:02 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-02-14 15:25:27 +0000
commit707224b57a9d646bbeb619bfe1054e9e4c021b23 (patch)
treee8590d1fb8d27ec7b49ad147455b8cadda8b120c /documentation/ref-manual/technical-details.xml
parent8097a978cef998d82cc1e35e94b090b0c8bb264f (diff)
downloadpoky-707224b57a9d646bbeb619bfe1054e9e4c021b23.tar.gz
ref-manual, overview-manual, yocto-project-qs: Moved YP Components
Fixes [YOCTO #12370] Moved the "Yocto Project Components" section from the ref-manual to the overview-manual. This material falls into the "concepts" area and is being moved from the ref-manual. One link in the yocto-project-qs was affected and updated. Oh... another link in the ref-manual for a variable also fixed. (From yocto-docs rev: 75ced485bb223373591eb41d1b343d0c2b315345) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual/technical-details.xml')
-rw-r--r--documentation/ref-manual/technical-details.xml222
1 files changed, 0 insertions, 222 deletions
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index 5769cd619a..d0929bd756 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -13,228 +13,6 @@
13 x32, Wayland support, and Licenses. 13 x32, Wayland support, and Licenses.
14 </para> 14 </para>
15 15
16<section id='usingpoky-components'>
17 <title>Yocto Project Components</title>
18
19 <para>
20 The
21 <link linkend='bitbake-term'>BitBake</link>
22 task executor together with various types of configuration files form
23 the OpenEmbedded Core.
24 This section overviews these components by describing their use and
25 how they interact.
26 </para>
27
28 <para>
29 BitBake handles the parsing and execution of the data files.
30 The data itself is of various types:
31 <itemizedlist>
32 <listitem><para><emphasis>Recipes:</emphasis> Provides details
33 about particular pieces of software.
34 </para></listitem>
35 <listitem><para><emphasis>Class Data:</emphasis> Abstracts
36 common build information (e.g. how to build a Linux kernel).
37 </para></listitem>
38 <listitem><para><emphasis>Configuration Data:</emphasis> Defines
39 machine-specific settings, policy decisions, and so forth.
40 Configuration data acts as the glue to bind everything
41 together.
42 </para></listitem>
43 </itemizedlist>
44 </para>
45
46 <para>
47 BitBake knows how to combine multiple data sources together and refers
48 to each data source as a layer.
49 For information on layers, see the
50 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and
51 Creating Layers</ulink>" section of the Yocto Project Development
52 Tasks Manual.
53 </para>
54
55 <para>
56 Following are some brief details on these core components.
57 For additional information on how these components interact during
58 a build, see the
59 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#development-concepts'>Development Concepts</ulink>"
60 section in the Yocto Project Overview Manual.
61 </para>
62
63 <section id='usingpoky-components-bitbake'>
64 <title>BitBake</title>
65
66 <para>
67 BitBake is the tool at the heart of the OpenEmbedded build system
68 and is responsible for parsing the
69 <link linkend='metadata'>Metadata</link>,
70 generating a list of tasks from it, and then executing those tasks.
71 </para>
72
73 <para>
74 This section briefly introduces BitBake.
75 If you want more information on BitBake, see the
76 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>.
77 </para>
78
79 <para>
80 To see a list of the options BitBake supports, use either of
81 the following commands:
82 <literallayout class='monospaced'>
83 $ bitbake -h
84 $ bitbake --help
85 </literallayout>
86 </para>
87
88 <para>
89 The most common usage for BitBake is <filename>bitbake <replaceable>packagename</replaceable></filename>, where
90 <filename>packagename</filename> is the name of the package you want to build
91 (referred to as the "target" in this manual).
92 The target often equates to the first part of a recipe's filename
93 (e.g. "foo" for a recipe named
94 <filename>foo_1.3.0-r0.bb</filename>).
95 So, to process the <filename>matchbox-desktop_1.2.3.bb</filename> recipe file, you
96 might type the following:
97 <literallayout class='monospaced'>
98 $ bitbake matchbox-desktop
99 </literallayout>
100 Several different versions of <filename>matchbox-desktop</filename> might exist.
101 BitBake chooses the one selected by the distribution configuration.
102 You can get more details about how BitBake chooses between different
103 target versions and providers in the
104 "<ulink url='&YOCTO_DOCS_BB_URL;#bb-bitbake-preferences'>Preferences</ulink>"
105 section of the BitBake User Manual.
106 </para>
107
108 <para>
109 BitBake also tries to execute any dependent tasks first.
110 So for example, before building <filename>matchbox-desktop</filename>, BitBake
111 would build a cross compiler and <filename>glibc</filename> if they had not already
112 been built.
113 </para>
114
115 <para>
116 A useful BitBake option to consider is the <filename>-k</filename> or
117 <filename>--continue</filename> option.
118 This option instructs BitBake to try and continue processing the job
119 as long as possible even after encountering an error.
120 When an error occurs, the target that
121 failed and those that depend on it cannot be remade.
122 However, when you use this option other dependencies can still be
123 processed.
124 </para>
125 </section>
126
127 <section id='usingpoky-components-metadata'>
128 <title>Metadata (Recipes)</title>
129
130 <para>
131 Files that have the <filename>.bb</filename> suffix are "recipes"
132 files.
133 In general, a recipe contains information about a single piece of
134 software.
135 This information includes the location from which to download the
136 unaltered source, any source patches to be applied to that source
137 (if needed), which special configuration options to apply,
138 how to compile the source files, and how to package the compiled
139 output.
140 </para>
141
142 <para>
143 The term "package" is sometimes used to refer to recipes. However,
144 since the word "package" is used for the packaged output from the OpenEmbedded
145 build system (i.e. <filename>.ipk</filename> or <filename>.deb</filename> files),
146 this document avoids using the term "package" when referring to recipes.
147 </para>
148 </section>
149
150 <section id='metadata-virtual-providers'>
151 <title>Metadata (Virtual Providers)</title>
152
153 <para>
154 Prior to the build, if you know that several different recipes
155 provide the same functionality, you can use a virtual provider
156 (i.e. <filename>virtual/*</filename>) as a placeholder for the
157 actual provider.
158 The actual provider would be determined at build
159 time.
160 In this case, you should add <filename>virtual/*</filename>
161 to <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>,
162 rather than listing the specified provider.
163 You would select the actual provider by setting the
164 <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>
165 variable (i.e. <filename>PREFERRED_PROVIDER_virtual/*</filename>)
166 in the build's configuration file (e.g.
167 <filename>poky/build/conf/local.conf</filename>).
168 <note>
169 Any recipe that PROVIDES a <filename>virtual/*</filename> item
170 that is ultimately not selected through
171 <filename>PREFERRED_PROVIDER</filename> does not get built.
172 Preventing these recipes from building is usually the desired
173 behavior since this mechanism's purpose is to select between
174 mutually exclusive alternative providers.
175 </note>
176 </para>
177
178 <para>
179 The following lists specific examples of virtual providers:
180 <itemizedlist>
181 <listitem><para>
182 <filename>virtual/mesa</filename>:
183 Provides <filename>gbm.pc</filename>.
184 </para></listitem>
185 <listitem><para>
186 <filename>virtual/egl</filename>:
187 Provides <filename>egl.pc</filename> and possibly
188 <filename>wayland-egl.pc</filename>.
189 </para></listitem>
190 <listitem><para>
191 <filename>virtual/libgl</filename>:
192 Provides <filename>gl.pc</filename> (i.e. libGL).
193 </para></listitem>
194 <listitem><para>
195 <filename>virtual/libgles1</filename>:
196 Provides <filename>glesv1_cm.pc</filename>
197 (i.e. libGLESv1_CM).
198 </para></listitem>
199 <listitem><para>
200 <filename>virtual/libgles2</filename>:
201 Provides <filename>glesv2.pc</filename> (i.e. libGLESv2).
202 </para></listitem>
203 </itemizedlist>
204 </para>
205 </section>
206
207 <section id='usingpoky-components-classes'>
208 <title>Classes</title>
209
210 <para>
211 Class files (<filename>.bbclass</filename>) contain information that
212 is useful to share between
213 <link linkend='metadata'>Metadata</link> files.
214 An example is the
215 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
216 class, which contains common settings for any application that
217 Autotools uses.
218 The "<link linkend='ref-classes'>Classes</link>" chapter provides
219 details about classes and how to use them.
220 </para>
221 </section>
222
223 <section id='usingpoky-components-configuration'>
224 <title>Configuration</title>
225
226 <para>
227 The configuration files (<filename>.conf</filename>) define various configuration variables
228 that govern the OpenEmbedded build process.
229 These files fall into several areas that define machine configuration options,
230 distribution configuration options, compiler tuning options, general common configuration
231 options, and user configuration options in <filename>local.conf</filename>, which is found
232 in the
233 <link linkend='build-directory'>Build Directory</link>.
234 </para>
235 </section>
236</section>
237
238<section id="cross-development-toolchain-generation"> 16<section id="cross-development-toolchain-generation">
239 <title>Cross-Development Toolchain Generation</title> 17 <title>Cross-Development Toolchain Generation</title>
240 18
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-10 17:49:28 +0000