summaryrefslogtreecommitdiffstats
path: root/documentation/overview-manual
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/overview-manual
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/overview-manual')
-rw-r--r--documentation/overview-manual/overview-concepts.xml368
1 files changed, 308 insertions, 60 deletions
diff --git a/documentation/overview-manual/overview-concepts.xml b/documentation/overview-manual/overview-concepts.xml
index dea30bc907..aa8d35e3f9 100644
--- a/documentation/overview-manual/overview-concepts.xml
+++ b/documentation/overview-manual/overview-concepts.xml
@@ -6,72 +6,320 @@
6<title>Yocto Project Concepts</title> 6<title>Yocto Project Concepts</title>
7 7
8 <para> 8 <para>
9 This chapter presents key Yocto Project concepts. 9 This chapter describes concepts for various areas of the Yocto Project.
10 Currently, topics include Yocto Project components, cross-development
11 generation, shared state (sstate) cache, runtime dependencies,
12 Pseudo and Fakeroot, x32 psABI, Wayland support, and Licenses.
10 </para> 13 </para>
11 14
12<section id='x32'> 15 <section id='yocto-project-components'>
13 <title>x32 psABI</title> 16 <title>Yocto Project Components</title>
14 17
15 <para> 18 <para>
16 x32 processor-specific Application Binary Interface 19 The
17 (<ulink url='https://software.intel.com/en-us/node/628948'>x32 psABI</ulink>) 20 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
18 is a native 32-bit processor-specific ABI for 21 task executor together with various types of configuration files
19 <trademark class='registered'>Intel</trademark> 64 (x86-64) 22 form the OpenEmbedded Core.
20 architectures. 23 This section overviews these components by describing their use and
21 An ABI defines the calling conventions between functions in a 24 how they interact.
22 processing environment. 25 </para>
23 The interface determines what registers are used and what the sizes are
24 for various C data types.
25 </para>
26 26
27 <para> 27 <para>
28 Some processing environments prefer using 32-bit applications even when 28 BitBake handles the parsing and execution of the data files.
29 running on Intel 64-bit platforms. 29 The data itself is of various types:
30 Consider the i386 psABI, which is a very old 32-bit ABI for Intel 30 <itemizedlist>
31 64-bit platforms. 31 <listitem><para>
32 The i386 psABI does not provide efficient use and access of the 32 <emphasis>Recipes:</emphasis>
33 Intel 64-bit processor resources, leaving the system underutilized. 33 Provides details about particular pieces of software.
34 Now consider the x86_64 psABI. 34 </para></listitem>
35 This ABI is newer and uses 64-bits for data sizes and program pointers. 35 <listitem><para>
36 The extra bits increase the footprint size of the programs, libraries, 36 <emphasis>Class Data:</emphasis>
37 and also increases the memory and file system size requirements. 37 Abstracts common build information (e.g. how to build a
38 Executing under the x32 psABI enables user programs to utilize CPU 38 Linux kernel).
39 and system resources more efficiently while keeping the memory 39 </para></listitem>
40 footprint of the applications low. 40 <listitem><para>
41 Extra bits are used for registers but not for addressing mechanisms. 41 <emphasis>Configuration Data:</emphasis>
42 </para> 42 Defines machine-specific settings, policy decisions, and
43 so forth.
44 Configuration data acts as the glue to bind everything
45 together.
46 </para></listitem>
47 </itemizedlist>
48 </para>
43 49
44 <para> 50 <para>
45 The Yocto Project supports the final specifications of x32 psABI 51 BitBake knows how to combine multiple data sources together and
46 as follows: 52 refers to each data source as a layer.
47 <itemizedlist> 53 For information on layers, see the
48 <listitem><para> 54 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
49 You can create packages and images in x32 psABI format on 55 section of the Yocto Project Development Tasks Manual.
50 x86_64 architecture targets. 56 </para>
51 </para></listitem>
52 <listitem><para>
53 You can successfully build recipes with the x32 toolchain.
54 </para></listitem>
55 <listitem><para>
56 You can create and boot
57 <filename>core-image-minimal</filename> and
58 <filename>core-image-sato</filename> images.
59 </para></listitem>
60 <listitem><para>
61 RPM Package Manager (RPM) support exists for x32 binaries.
62 </para></listitem>
63 <listitem><para>
64 Support for large images exists.
65 </para></listitem>
66 </itemizedlist>
67 </para>
68 57
69 <para> 58 <para>
70 For steps on how to use x32 psABI, see the 59 Following are some brief details on these core components.
71 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-x32-psabi'>Using x32 psABI</ulink>" 60 For additional information on how these components interact during
72 section in the Yocto Project Development Tasks Manual. 61 a build, see the
73 </para> 62 "<link linkend='development-concepts'>Development Concepts</link>"
74</section> 63 section.
64 </para>
65
66 <section id='usingpoky-components-bitbake'>
67 <title>BitBake</title>
68
69 <para>
70 BitBake is the tool at the heart of the OpenEmbedded build
71 system and is responsible for parsing the
72 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>,
73 generating a list of tasks from it, and then executing those
74 tasks.
75 </para>
76
77 <para>
78 This section briefly introduces BitBake.
79 If you want more information on BitBake, see the
80 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>.
81 </para>
82
83 <para>
84 To see a list of the options BitBake supports, use either of
85 the following commands:
86 <literallayout class='monospaced'>
87 $ bitbake -h
88 $ bitbake --help
89 </literallayout>
90 </para>
91
92 <para>
93 The most common usage for BitBake is
94 <filename>bitbake <replaceable>packagename</replaceable></filename>,
95 where <filename>packagename</filename> is the name of the
96 package you want to build (referred to as the "target" in this
97 manual).
98 The target often equates to the first part of a recipe's
99 filename (e.g. "foo" for a recipe named
100 <filename>foo_1.3.0-r0.bb</filename>).
101 So, to process the
102 <filename>matchbox-desktop_1.2.3.bb</filename> recipe file, you
103 might type the following:
104 <literallayout class='monospaced'>
105 $ bitbake matchbox-desktop
106 </literallayout>
107 Several different versions of
108 <filename>matchbox-desktop</filename> might exist.
109 BitBake chooses the one selected by the distribution
110 configuration.
111 You can get more details about how BitBake chooses between
112 different target versions and providers in the
113 "<ulink url='&YOCTO_DOCS_BB_URL;#bb-bitbake-preferences'>Preferences</ulink>"
114 section of the BitBake User Manual.
115 </para>
116
117 <para>
118 BitBake also tries to execute any dependent tasks first.
119 So for example, before building
120 <filename>matchbox-desktop</filename>, BitBake would build a
121 cross compiler and <filename>glibc</filename> if they had not
122 already been built.
123 </para>
124
125 <para>
126 A useful BitBake option to consider is the
127 <filename>-k</filename> or <filename>--continue</filename>
128 option.
129 This option instructs BitBake to try and continue processing
130 the job as long as possible even after encountering an error.
131 When an error occurs, the target that failed and those that
132 depend on it cannot be remade.
133 However, when you use this option other dependencies can
134 still be processed.
135 </para>
136 </section>
137
138 <section id='usingpoky-components-metadata'>
139 <title>Metadata (Recipes)</title>
140
141 <para>
142 Files that have the <filename>.bb</filename> suffix are
143 "recipes" files.
144 In general, a recipe contains information about a single piece
145 of software.
146 This information includes the location from which to download
147 the unaltered source, any source patches to be applied to that
148 source (if needed), which special configuration options to
149 apply, how to compile the source files, and how to package the
150 compiled output.
151 </para>
152
153 <para>
154 The term "package" is sometimes used to refer to recipes.
155 However, since the word "package" is used for the packaged
156 output from the OpenEmbedded build system (i.e.
157 <filename>.ipk</filename> or <filename>.deb</filename> files),
158 this document avoids using the term "package" when referring
159 to recipes.
160 </para>
161 </section>
162
163 <section id='metadata-virtual-providers'>
164 <title>Metadata (Virtual Providers)</title>
165
166 <para>
167 Prior to the build, if you know that several different recipes
168 provide the same functionality, you can use a virtual provider
169 (i.e. <filename>virtual/*</filename>) as a placeholder for the
170 actual provider.
171 The actual provider would be determined at build time.
172 In this case, you should add <filename>virtual/*</filename>
173 to
174 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
175 rather than listing the specified provider.
176 You would select the actual provider by setting the
177 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
178 variable (i.e.
179 <filename>PREFERRED_PROVIDER_virtual/*</filename>)
180 in the build's configuration file (e.g.
181 <filename>poky/build/conf/local.conf</filename>).
182 <note>
183 Any recipe that PROVIDES a <filename>virtual/*</filename>
184 item that is ultimately not selected through
185 <filename>PREFERRED_PROVIDER</filename> does not get built.
186 Preventing these recipes from building is usually the
187 desired behavior since this mechanism's purpose is to
188 select between mutually exclusive alternative providers.
189 </note>
190 </para>
191
192 <para>
193 The following lists specific examples of virtual providers:
194 <itemizedlist>
195 <listitem><para>
196 <filename>virtual/mesa</filename>:
197 Provides <filename>gbm.pc</filename>.
198 </para></listitem>
199 <listitem><para>
200 <filename>virtual/egl</filename>:
201 Provides <filename>egl.pc</filename> and possibly
202 <filename>wayland-egl.pc</filename>.
203 </para></listitem>
204 <listitem><para>
205 <filename>virtual/libgl</filename>:
206 Provides <filename>gl.pc</filename> (i.e. libGL).
207 </para></listitem>
208 <listitem><para>
209 <filename>virtual/libgles1</filename>:
210 Provides <filename>glesv1_cm.pc</filename>
211 (i.e. libGLESv1_CM).
212 </para></listitem>
213 <listitem><para>
214 <filename>virtual/libgles2</filename>:
215 Provides <filename>glesv2.pc</filename>
216 (i.e. libGLESv2).
217 </para></listitem>
218 </itemizedlist>
219 </para>
220 </section>
221
222 <section id='usingpoky-components-classes'>
223 <title>Classes</title>
224
225 <para>
226 Class files (<filename>.bbclass</filename>) contain information
227 that is useful to share between
228 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
229 files.
230 An example is the
231 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
232 class, which contains common settings for any application that
233 Autotools uses.
234 The
235 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>Classes</ulink>"
236 chapter in the Yocto Project Reference Manual provides
237 details about classes and how to use them.
238 </para>
239 </section>
240
241 <section id='usingpoky-components-configuration'>
242 <title>Configuration</title>
243
244 <para>
245 The configuration files (<filename>.conf</filename>) define
246 various configuration variables that govern the OpenEmbedded
247 build process.
248 These files fall into several areas that define machine
249 configuration options, distribution configuration options,
250 compiler tuning options, general common configuration options,
251 and user configuration options in
252 <filename>local.conf</filename>, which is found in the
253 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
254 </para>
255 </section>
256 </section>
257
258 <section id='x32'>
259 <title>x32 psABI</title>
260
261 <para>
262 x32 processor-specific Application Binary Interface
263 (<ulink url='https://software.intel.com/en-us/node/628948'>x32 psABI</ulink>)
264 is a native 32-bit processor-specific ABI for
265 <trademark class='registered'>Intel</trademark> 64 (x86-64)
266 architectures.
267 An ABI defines the calling conventions between functions in a
268 processing environment.
269 The interface determines what registers are used and what the sizes are
270 for various C data types.
271 </para>
272
273 <para>
274 Some processing environments prefer using 32-bit applications even
275 when running on Intel 64-bit platforms.
276 Consider the i386 psABI, which is a very old 32-bit ABI for Intel
277 64-bit platforms.
278 The i386 psABI does not provide efficient use and access of the
279 Intel 64-bit processor resources, leaving the system underutilized.
280 Now consider the x86_64 psABI.
281 This ABI is newer and uses 64-bits for data sizes and program
282 pointers.
283 The extra bits increase the footprint size of the programs,
284 libraries, and also increases the memory and file system size
285 requirements.
286 Executing under the x32 psABI enables user programs to utilize CPU
287 and system resources more efficiently while keeping the memory
288 footprint of the applications low.
289 Extra bits are used for registers but not for addressing mechanisms.
290 </para>
291
292 <para>
293 The Yocto Project supports the final specifications of x32 psABI
294 as follows:
295 <itemizedlist>
296 <listitem><para>
297 You can create packages and images in x32 psABI format on
298 x86_64 architecture targets.
299 </para></listitem>
300 <listitem><para>
301 You can successfully build recipes with the x32 toolchain.
302 </para></listitem>
303 <listitem><para>
304 You can create and boot
305 <filename>core-image-minimal</filename> and
306 <filename>core-image-sato</filename> images.
307 </para></listitem>
308 <listitem><para>
309 RPM Package Manager (RPM) support exists for x32 binaries.
310 </para></listitem>
311 <listitem><para>
312 Support for large images exists.
313 </para></listitem>
314 </itemizedlist>
315 </para>
316
317 <para>
318 For steps on how to use x32 psABI, see the
319 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-x32-psabi'>Using x32 psABI</ulink>"
320 section in the Yocto Project Development Tasks Manual.
321 </para>
322 </section>
75</chapter> 323</chapter>
76<!-- 324<!--
77vim: expandtab tw=80 ts=4 325vim: expandtab tw=80 ts=4
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-05 16:20:27 +0000