summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-01-30 13:42:02 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-02-14 15:25:30 +0000
commit1f0a763637b5d5dea3ab11d6faeb3d6d0aa3f567 (patch)
tree2cf9c207f1f368c83c1ada0e4416f98920b948a2 /documentation
parent8a99429c0dc96a09f1089cc8a851119c128a8120 (diff)
downloadpoky-1f0a763637b5d5dea3ab11d6faeb3d6d0aa3f567.tar.gz
getting-started: Removed "concepts.xml" file
This file was for a deeper concepts chapter. It will go into the new Yocto Project Concepts Manual. Removing it required deleting the *.xml file and updating getting-started.xml to not include it in the build. (From yocto-docs rev: 2df213c1cdba8f48918e8240de47c1758352807d) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/getting-started/getting-started-concepts.xml1929
-rw-r--r--documentation/getting-started/getting-started.xml4
2 files changed, 1 insertions, 1932 deletions
diff --git a/documentation/getting-started/getting-started-concepts.xml b/documentation/getting-started/getting-started-concepts.xml
deleted file mode 100644
index 02fc9d08d2..0000000000
--- a/documentation/getting-started/getting-started-concepts.xml
+++ /dev/null
@@ -1,1929 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='getting-started-concepts'>
6<title>Yocto Project Concepts</title>
7
8 <para>
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.
13 </para>
14
15 <section id='yocto-project-components'>
16 <title>Yocto Project Components</title>
17
18 <para>
19 The
20 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
21 task executor together with various types of configuration files
22 form the OpenEmbedded Core.
23 This section overviews these components by describing their use and
24 how they interact.
25 </para>
26
27 <para>
28 BitBake handles the parsing and execution of the data files.
29 The data itself is of various types:
30 <itemizedlist>
31 <listitem><para>
32 <emphasis>Recipes:</emphasis>
33 Provides details about particular pieces of software.
34 </para></listitem>
35 <listitem><para>
36 <emphasis>Class Data:</emphasis>
37 Abstracts common build information (e.g. how to build a
38 Linux kernel).
39 </para></listitem>
40 <listitem><para>
41 <emphasis>Configuration Data:</emphasis>
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>
49
50 <para>
51 BitBake knows how to combine multiple data sources together and
52 refers to each data source as a layer.
53 For information on layers, see the
54 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
55 section of the Yocto Project Development Tasks Manual.
56 </para>
57
58 <para>
59 Following are some brief details on these core components.
60 For additional information on how these components interact during
61 a build, see the
62 "<link linkend='development-concepts'>Development Concepts</link>"
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="cross-development-toolchain-generation">
259 <title>Cross-Development Toolchain Generation</title>
260
261 <para>
262 The Yocto Project does most of the work for you when it comes to
263 creating
264 <ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain'>cross-development toolchains</ulink>.
265 This section provides some technical background on how
266 cross-development toolchains are created and used.
267 For more information on toolchains, you can also see the
268 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
269 manual.
270 </para>
271
272 <para>
273 In the Yocto Project development environment, cross-development
274 toolchains are used to build the image and applications that run
275 on the target hardware.
276 With just a few commands, the OpenEmbedded build system creates
277 these necessary toolchains for you.
278 </para>
279
280 <para>
281 The following figure shows a high-level build environment regarding
282 toolchain construction and use.
283 </para>
284
285 <para>
286 <imagedata fileref="figures/cross-development-toolchains.png" width="8in" depth="6in" align="center" />
287 </para>
288
289 <para>
290 Most of the work occurs on the Build Host.
291 This is the machine used to build images and generally work within the
292 the Yocto Project environment.
293 When you run BitBake to create an image, the OpenEmbedded build system
294 uses the host <filename>gcc</filename> compiler to bootstrap a
295 cross-compiler named <filename>gcc-cross</filename>.
296 The <filename>gcc-cross</filename> compiler is what BitBake uses to
297 compile source files when creating the target image.
298 You can think of <filename>gcc-cross</filename> simply as an
299 automatically generated cross-compiler that is used internally within
300 BitBake only.
301 <note>
302 The extensible SDK does not use
303 <filename>gcc-cross-canadian</filename> since this SDK
304 ships a copy of the OpenEmbedded build system and the sysroot
305 within it contains <filename>gcc-cross</filename>.
306 </note>
307 </para>
308
309 <para>
310 The chain of events that occurs when <filename>gcc-cross</filename> is
311 bootstrapped is as follows:
312 <literallayout class='monospaced'>
313 gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime
314 </literallayout>
315 <itemizedlist>
316 <listitem><para>
317 <filename>gcc</filename>:
318 The build host's GNU Compiler Collection (GCC).
319 </para></listitem>
320 <listitem><para>
321 <filename>binutils-cross</filename>:
322 The bare minimum binary utilities needed in order to run
323 the <filename>gcc-cross-initial</filename> phase of the
324 bootstrap operation.
325 </para></listitem>
326 <listitem><para>
327 <filename>gcc-cross-initial</filename>:
328 An early stage of the bootstrap process for creating
329 the cross-compiler.
330 This stage builds enough of the <filename>gcc-cross</filename>,
331 the C library, and other pieces needed to finish building the
332 final cross-compiler in later stages.
333 This tool is a "native" package (i.e. it is designed to run on
334 the build host).
335 </para></listitem>
336 <listitem><para>
337 <filename>linux-libc-headers</filename>:
338 Headers needed for the cross-compiler.
339 </para></listitem>
340 <listitem><para>
341 <filename>glibc-initial</filename>:
342 An initial version of the Embedded GLIBC needed to bootstrap
343 <filename>glibc</filename>.
344 </para></listitem>
345 <listitem><para>
346 <filename>gcc-cross</filename>:
347 The final stage of the bootstrap process for the
348 cross-compiler.
349 This stage results in the actual cross-compiler that
350 BitBake uses when it builds an image for a targeted
351 device.
352 <note>
353 If you are replacing this cross compiler toolchain
354 with a custom version, you must replace
355 <filename>gcc-cross</filename>.
356 </note>
357 This tool is also a "native" package (i.e. it is
358 designed to run on the build host).
359 </para></listitem>
360 <listitem><para>
361 <filename>gcc-runtime</filename>:
362 Runtime libraries resulting from the toolchain bootstrapping
363 process.
364 This tool produces a binary that consists of the
365 runtime libraries need for the targeted device.
366 </para></listitem>
367 </itemizedlist>
368 </para>
369
370 <para>
371 You can use the OpenEmbedded build system to build an installer for
372 the relocatable SDK used to develop applications.
373 When you run the installer, it installs the toolchain, which contains
374 the development tools (e.g., the
375 <filename>gcc-cross-canadian</filename>),
376 <filename>binutils-cross-canadian</filename>, and other
377 <filename>nativesdk-*</filename> tools,
378 which are tools native to the SDK (i.e. native to
379 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_ARCH'><filename>SDK_ARCH</filename></ulink>),
380 you need to cross-compile and test your software.
381 The figure shows the commands you use to easily build out this
382 toolchain.
383 This cross-development toolchain is built to execute on the
384 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>,
385 which might or might not be the same
386 machine as the Build Host.
387 <note>
388 If your target architecture is supported by the Yocto Project,
389 you can take advantage of pre-built images that ship with the
390 Yocto Project and already contain cross-development toolchain
391 installers.
392 </note>
393 </para>
394
395 <para>
396 Here is the bootstrap process for the relocatable toolchain:
397 <literallayout class='monospaced'>
398 gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers ->
399 glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian
400 </literallayout>
401 <itemizedlist>
402 <listitem><para>
403 <filename>gcc</filename>:
404 The build host's GNU Compiler Collection (GCC).
405 </para></listitem>
406 <listitem><para>
407 <filename>binutils-crosssdk</filename>:
408 The bare minimum binary utilities needed in order to run
409 the <filename>gcc-crosssdk-initial</filename> phase of the
410 bootstrap operation.
411 </para></listitem>
412 <listitem><para>
413 <filename>gcc-crosssdk-initial</filename>:
414 An early stage of the bootstrap process for creating
415 the cross-compiler.
416 This stage builds enough of the
417 <filename>gcc-crosssdk</filename> and supporting pieces so that
418 the final stage of the bootstrap process can produce the
419 finished cross-compiler.
420 This tool is a "native" binary that runs on the build host.
421 </para></listitem>
422 <listitem><para>
423 <filename>linux-libc-headers</filename>:
424 Headers needed for the cross-compiler.
425 </para></listitem>
426 <listitem><para>
427 <filename>glibc-initial</filename>:
428 An initial version of the Embedded GLIBC needed to bootstrap
429 <filename>nativesdk-glibc</filename>.
430 </para></listitem>
431 <listitem><para>
432 <filename>nativesdk-glibc</filename>:
433 The Embedded GLIBC needed to bootstrap the
434 <filename>gcc-crosssdk</filename>.
435 </para></listitem>
436 <listitem><para>
437 <filename>gcc-crosssdk</filename>:
438 The final stage of the bootstrap process for the
439 relocatable cross-compiler.
440 The <filename>gcc-crosssdk</filename> is a transitory compiler
441 and never leaves the build host.
442 Its purpose is to help in the bootstrap process to create the
443 eventual relocatable <filename>gcc-cross-canadian</filename>
444 compiler, which is relocatable.
445 This tool is also a "native" package (i.e. it is
446 designed to run on the build host).
447 </para></listitem>
448 <listitem><para>
449 <filename>gcc-cross-canadian</filename>:
450 The final relocatable cross-compiler.
451 When run on the
452 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>,
453 this tool
454 produces executable code that runs on the target device.
455 Only one cross-canadian compiler is produced per architecture
456 since they can be targeted at different processor optimizations
457 using configurations passed to the compiler through the
458 compile commands.
459 This circumvents the need for multiple compilers and thus
460 reduces the size of the toolchains.
461 </para></listitem>
462 </itemizedlist>
463 </para>
464
465 <note>
466 For information on advantages gained when building a
467 cross-development toolchain installer, see the
468 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>"
469 section in the Yocto Project Application Development and the
470 Extensible Software Development Kit (eSDK) manual.
471 </note>
472 </section>
473
474
475
476
477 <section id="shared-state-cache">
478 <title>Shared State Cache</title>
479
480 <para>
481 By design, the OpenEmbedded build system builds everything from
482 scratch unless BitBake can determine that parts do not need to be
483 rebuilt.
484 Fundamentally, building from scratch is attractive as it means all
485 parts are built fresh and there is no possibility of stale data
486 causing problems.
487 When developers hit problems, they typically default back to
488 building from scratch so they know the state of things from the
489 start.
490 </para>
491
492 <para>
493 Building an image from scratch is both an advantage and a
494 disadvantage to the process.
495 As mentioned in the previous paragraph, building from scratch
496 ensures that everything is current and starts from a known state.
497 However, building from scratch also takes much longer as it
498 generally means rebuilding things that do not necessarily need
499 to be rebuilt.
500 </para>
501
502 <para>
503 The Yocto Project implements shared state code that supports
504 incremental builds.
505 The implementation of the shared state code answers the following
506 questions that were fundamental roadblocks within the OpenEmbedded
507 incremental build support system:
508 <itemizedlist>
509 <listitem><para>
510 What pieces of the system have changed and what pieces have
511 not changed?
512 </para></listitem>
513 <listitem><para>
514 How are changed pieces of software removed and replaced?
515 </para></listitem>
516 <listitem><para>
517 How are pre-built components that do not need to be rebuilt
518 from scratch used when they are available?
519 </para></listitem>
520 </itemizedlist>
521 </para>
522
523 <para>
524 For the first question, the build system detects changes in the
525 "inputs" to a given task by creating a checksum (or signature) of
526 the task's inputs.
527 If the checksum changes, the system assumes the inputs have changed
528 and the task needs to be rerun.
529 For the second question, the shared state (sstate) code tracks
530 which tasks add which output to the build process.
531 This means the output from a given task can be removed, upgraded
532 or otherwise manipulated.
533 The third question is partly addressed by the solution for the
534 second question assuming the build system can fetch the sstate
535 objects from remote locations and install them if they are deemed
536 to be valid.
537 <note>
538 The OpenEmbedded build system does not maintain
539 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
540 information as part of the shared state packages.
541 Consequently, considerations exist that affect maintaining
542 shared state feeds.
543 For information on how the OpenEmbedded build system
544 works with packages and can track incrementing
545 <filename>PR</filename> information, see the
546 "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"
547 section in the Yocto Project Development Tasks Manual.
548 </note>
549 </para>
550
551 <para>
552 The rest of this section goes into detail about the overall
553 incremental build architecture, the checksums (signatures), shared
554 state, and some tips and tricks.
555 </para>
556
557 <section id='overall-architecture'>
558 <title>Overall Architecture</title>
559
560 <para>
561 When determining what parts of the system need to be built,
562 BitBake works on a per-task basis rather than a per-recipe
563 basis.
564 You might wonder why using a per-task basis is preferred over
565 a per-recipe basis.
566 To help explain, consider having the IPK packaging backend
567 enabled and then switching to DEB.
568 In this case, the
569 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
570 and
571 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
572 task outputs are still valid.
573 However, with a per-recipe approach, the build would not
574 include the <filename>.deb</filename> files.
575 Consequently, you would have to invalidate the whole build and
576 rerun it.
577 Rerunning everything is not the best solution.
578 Also, in this case, the core must be "taught" much about
579 specific tasks.
580 This methodology does not scale well and does not allow users
581 to easily add new tasks in layers or as external recipes
582 without touching the packaged-staging core.
583 </para>
584 </section>
585
586 <section id='overview-checksums'>
587 <title>Checksums (Signatures)</title>
588
589 <para>
590 The shared state code uses a checksum, which is a unique
591 signature of a task's inputs, to determine if a task needs to
592 be run again.
593 Because it is a change in a task's inputs that triggers a
594 rerun, the process needs to detect all the inputs to a given
595 task.
596 For shell tasks, this turns out to be fairly easy because
597 the build process generates a "run" shell script for each task
598 and it is possible to create a checksum that gives you a good
599 idea of when the task's data changes.
600 </para>
601
602 <para>
603 To complicate the problem, there are things that should not be
604 included in the checksum.
605 First, there is the actual specific build path of a given
606 task - the
607 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>.
608 It does not matter if the work directory changes because it
609 should not affect the output for target packages.
610 Also, the build process has the objective of making native
611 or cross packages relocatable.
612 <note>
613 Both native and cross packages run on the build host.
614 However, cross packages generate output for the target
615 architecture.
616 </note>
617 The checksum therefore needs to exclude
618 <filename>WORKDIR</filename>.
619 The simplistic approach for excluding the work directory is to
620 set <filename>WORKDIR</filename> to some fixed value and
621 create the checksum for the "run" script.
622 </para>
623
624 <para>
625 Another problem results from the "run" scripts containing
626 functions that might or might not get called.
627 The incremental build solution contains code that figures out
628 dependencies between shell functions.
629 This code is used to prune the "run" scripts down to the
630 minimum set, thereby alleviating this problem and making the
631 "run" scripts much more readable as a bonus.
632 </para>
633
634 <para>
635 So far we have solutions for shell scripts.
636 What about Python tasks?
637 The same approach applies even though these tasks are more
638 difficult.
639 The process needs to figure out what variables a Python
640 function accesses and what functions it calls.
641 Again, the incremental build solution contains code that first
642 figures out the variable and function dependencies, and then
643 creates a checksum for the data used as the input to the task.
644 </para>
645
646 <para>
647 Like the <filename>WORKDIR</filename> case, situations exist
648 where dependencies should be ignored.
649 For these cases, you can instruct the build process to
650 ignore a dependency by using a line like the following:
651 <literallayout class='monospaced'>
652 PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
653 </literallayout>
654 This example ensures that the
655 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCHS'><filename>PACKAGE_ARCHS</filename></ulink>
656 variable does not depend on the value of
657 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>,
658 even if it does reference it.
659 </para>
660
661 <para>
662 Equally, there are cases where we need to add dependencies
663 BitBake is not able to find.
664 You can accomplish this by using a line like the following:
665 <literallayout class='monospaced'>
666 PACKAGE_ARCHS[vardeps] = "MACHINE"
667 </literallayout>
668 This example explicitly adds the <filename>MACHINE</filename>
669 variable as a dependency for
670 <filename>PACKAGE_ARCHS</filename>.
671 </para>
672
673 <para>
674 Consider a case with in-line Python, for example, where
675 BitBake is not able to figure out dependencies.
676 When running in debug mode (i.e. using
677 <filename>-DDD</filename>), BitBake produces output when it
678 discovers something for which it cannot figure out dependencies.
679 The Yocto Project team has currently not managed to cover
680 those dependencies in detail and is aware of the need to fix
681 this situation.
682 </para>
683
684 <para>
685 Thus far, this section has limited discussion to the direct
686 inputs into a task.
687 Information based on direct inputs is referred to as the
688 "basehash" in the code.
689 However, there is still the question of a task's indirect
690 inputs - the things that were already built and present in the
691 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
692 The checksum (or signature) for a particular task needs to add
693 the hashes of all the tasks on which the particular task
694 depends.
695 Choosing which dependencies to add is a policy decision.
696 However, the effect is to generate a master checksum that
697 combines the basehash and the hashes of the task's
698 dependencies.
699 </para>
700
701 <para>
702 At the code level, there are a variety of ways both the
703 basehash and the dependent task hashes can be influenced.
704 Within the BitBake configuration file, we can give BitBake
705 some extra information to help it construct the basehash.
706 The following statement effectively results in a list of
707 global variable dependency excludes - variables never
708 included in any checksum:
709 <literallayout class='monospaced'>
710 BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \
711 SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \
712 USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \
713 PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \
714 CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX"
715 </literallayout>
716 The previous example excludes
717 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
718 since that variable is actually constructed as a path within
719 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>,
720 which is on the whitelist.
721 </para>
722
723 <para>
724 The rules for deciding which hashes of dependent tasks to
725 include through dependency chains are more complex and are
726 generally accomplished with a Python function.
727 The code in <filename>meta/lib/oe/sstatesig.py</filename> shows
728 two examples of this and also illustrates how you can insert
729 your own policy into the system if so desired.
730 This file defines the two basic signature generators
731 <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OE-Core</ulink>
732 uses: "OEBasic" and "OEBasicHash".
733 By default, there is a dummy "noop" signature handler enabled
734 in BitBake.
735 This means that behavior is unchanged from previous versions.
736 OE-Core uses the "OEBasicHash" signature handler by default
737 through this setting in the <filename>bitbake.conf</filename>
738 file:
739 <literallayout class='monospaced'>
740 BB_SIGNATURE_HANDLER ?= "OEBasicHash"
741 </literallayout>
742 The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename>
743 is the same as the "OEBasic" version but adds the task hash to
744 the stamp files.
745 This results in any
746 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
747 change that changes the task hash, automatically
748 causing the task to be run again.
749 This removes the need to bump
750 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
751 values, and changes to Metadata automatically ripple across
752 the build.
753 </para>
754
755 <para>
756 It is also worth noting that the end result of these
757 signature generators is to make some dependency and hash
758 information available to the build.
759 This information includes:
760 <itemizedlist>
761 <listitem><para>
762 <filename>BB_BASEHASH_task-</filename><replaceable>taskname</replaceable>:
763 The base hashes for each task in the recipe.
764 </para></listitem>
765 <listitem><para>
766 <filename>BB_BASEHASH_</filename><replaceable>filename</replaceable><filename>:</filename><replaceable>taskname</replaceable>:
767 The base hashes for each dependent task.
768 </para></listitem>
769 <listitem><para>
770 <filename>BBHASHDEPS_</filename><replaceable>filename</replaceable><filename>:</filename><replaceable>taskname</replaceable>:
771 The task dependencies for each task.
772 </para></listitem>
773 <listitem><para>
774 <filename>BB_TASKHASH</filename>:
775 The hash of the currently running task.
776 </para></listitem>
777 </itemizedlist>
778 </para>
779 </section>
780
781 <section id='shared-state'>
782 <title>Shared State</title>
783
784 <para>
785 Checksums and dependencies, as discussed in the previous
786 section, solve half the problem of supporting a shared state.
787 The other part of the problem is being able to use checksum
788 information during the build and being able to reuse or rebuild
789 specific components.
790 </para>
791
792 <para>
793 The
794 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-sstate'><filename>sstate</filename></ulink>
795 class is a relatively generic implementation of how to
796 "capture" a snapshot of a given task.
797 The idea is that the build process does not care about the
798 source of a task's output.
799 Output could be freshly built or it could be downloaded and
800 unpacked from somewhere - the build process does not need to
801 worry about its origin.
802 </para>
803
804 <para>
805 There are two types of output, one is just about creating a
806 directory in
807 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>.
808 A good example is the output of either
809 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
810 or
811 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>.
812 The other type of output occurs when a set of data is merged
813 into a shared directory tree such as the sysroot.
814 </para>
815
816 <para>
817 The Yocto Project team has tried to keep the details of the
818 implementation hidden in <filename>sstate</filename> class.
819 From a user's perspective, adding shared state wrapping to a task
820 is as simple as this
821 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-deploy'><filename>do_deploy</filename></ulink>
822 example taken from the
823 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-deploy'><filename>deploy</filename></ulink>
824 class:
825 <literallayout class='monospaced'>
826 DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
827 SSTATETASKS += "do_deploy"
828 do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"
829 do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"
830
831 python do_deploy_setscene () {
832 sstate_setscene(d)
833 }
834 addtask do_deploy_setscene
835 do_deploy[dirs] = "${DEPLOYDIR} ${B}"
836 </literallayout>
837 The following list explains the previous example:
838 <itemizedlist>
839 <listitem><para>
840 Adding "do_deploy" to <filename>SSTATETASKS</filename>
841 adds some required sstate-related processing, which is
842 implemented in the
843 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-sstate'><filename>sstate</filename></ulink>
844 class, to before and after the
845 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-deploy'><filename>do_deploy</filename></ulink>
846 task.
847 </para></listitem>
848 <listitem><para>
849 The
850 <filename>do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"</filename>
851 declares that <filename>do_deploy</filename> places its
852 output in <filename>${DEPLOYDIR}</filename> when run
853 normally (i.e. when not using the sstate cache).
854 This output becomes the input to the shared state cache.
855 </para></listitem>
856 <listitem><para>
857 The
858 <filename>do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"</filename>
859 line causes the contents of the shared state cache to be
860 copied to <filename>${DEPLOY_DIR_IMAGE}</filename>.
861 <note>
862 If <filename>do_deploy</filename> is not already in
863 the shared state cache or if its input checksum
864 (signature) has changed from when the output was
865 cached, the task will be run to populate the shared
866 state cache, after which the contents of the shared
867 state cache is copied to
868 <filename>${DEPLOY_DIR_IMAGE}</filename>.
869 If <filename>do_deploy</filename> is in the shared
870 state cache and its signature indicates that the
871 cached output is still valid (i.e. if no
872 relevant task inputs have changed), then the
873 contents of the shared state cache will be copied
874 directly to
875 <filename>${DEPLOY_DIR_IMAGE}</filename> by the
876 <filename>do_deploy_setscene</filename> task
877 instead, skipping the
878 <filename>do_deploy</filename> task.
879 </note>
880 </para></listitem>
881 <listitem><para>
882 The following task definition is glue logic needed to
883 make the previous settings effective:
884 <literallayout class='monospaced'>
885 python do_deploy_setscene () {
886 sstate_setscene(d)
887 }
888 addtask do_deploy_setscene
889 </literallayout>
890 <filename>sstate_setscene()</filename> takes the flags
891 above as input and accelerates the
892 <filename>do_deploy</filename> task through the
893 shared state cache if possible.
894 If the task was accelerated,
895 <filename>sstate_setscene()</filename> returns True.
896 Otherwise, it returns False, and the normal
897 <filename>do_deploy</filename> task runs.
898 For more information, see the
899 "<ulink url='&YOCTO_DOCS_BB_URL;#setscene'>setscene</ulink>"
900 section in the BitBake User Manual.
901 </para></listitem>
902 <listitem><para>
903 The <filename>do_deploy[dirs] = "${DEPLOYDIR} ${B}"</filename>
904 line creates <filename>${DEPLOYDIR}</filename> and
905 <filename>${B}</filename> before the
906 <filename>do_deploy</filename> task runs, and also sets
907 the current working directory of
908 <filename>do_deploy</filename> to
909 <filename>${B}</filename>.
910 For more information, see the
911 "<ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'>Variable Flags</ulink>"
912 section in the BitBake User Manual.
913 <note>
914 In cases where
915 <filename>sstate-inputdirs</filename> and
916 <filename>sstate-outputdirs</filename> would be the
917 same, you can use
918 <filename>sstate-plaindirs</filename>.
919 For example, to preserve the
920 <filename>${PKGD}</filename> and
921 <filename>${PKGDEST}</filename> output from the
922 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
923 task, use the following:
924 <literallayout class='monospaced'>
925 do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
926 </literallayout>
927 </note>
928 </para></listitem>
929 <listitem><para>
930 <filename>sstate-inputdirs</filename> and
931 <filename>sstate-outputdirs</filename> can also be used
932 with multiple directories.
933 For example, the following declares
934 <filename>PKGDESTWORK</filename> and
935 <filename>SHLIBWORK</filename> as shared state
936 input directories, which populates the shared state
937 cache, and <filename>PKGDATA_DIR</filename> and
938 <filename>SHLIBSDIR</filename> as the corresponding
939 shared state output directories:
940 <literallayout class='monospaced'>
941 do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
942 do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
943 </literallayout>
944 </para></listitem>
945 <listitem><para>
946 These methods also include the ability to take a
947 lockfile when manipulating shared state directory
948 structures, for cases where file additions or removals
949 are sensitive:
950 <literallayout class='monospaced'>
951 do_package[sstate-lockfile] = "${PACKAGELOCK}"
952 </literallayout>
953 </para></listitem>
954 </itemizedlist>
955 </para>
956
957 <para>
958 Behind the scenes, the shared state code works by looking in
959 <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>
960 and
961 <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink>
962 for shared state files.
963 Here is an example:
964 <literallayout class='monospaced'>
965 SSTATE_MIRRORS ?= "\
966 file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \
967 file://.* file:///some/local/dir/sstate/PATH"
968 </literallayout>
969 <note>
970 The shared state directory
971 (<filename>SSTATE_DIR</filename>) is organized into
972 two-character subdirectories, where the subdirectory
973 names are based on the first two characters of the hash.
974 If the shared state directory structure for a mirror has the
975 same structure as <filename>SSTATE_DIR</filename>, you must
976 specify "PATH" as part of the URI to enable the build system
977 to map to the appropriate subdirectory.
978 </note>
979 </para>
980
981 <para>
982 The shared state package validity can be detected just by
983 looking at the filename since the filename contains the task
984 checksum (or signature) as described earlier in this section.
985 If a valid shared state package is found, the build process
986 downloads it and uses it to accelerate the task.
987 </para>
988
989 <para>
990 The build processes use the <filename>*_setscene</filename>
991 tasks for the task acceleration phase.
992 BitBake goes through this phase before the main execution
993 code and tries to accelerate any tasks for which it can find
994 shared state packages.
995 If a shared state package for a task is available, the
996 shared state package is used.
997 This means the task and any tasks on which it is dependent
998 are not executed.
999 </para>
1000
1001 <para>
1002 As a real world example, the aim is when building an IPK-based
1003 image, only the
1004 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></ulink>
1005 tasks would have their shared state packages fetched and
1006 extracted.
1007 Since the sysroot is not used, it would never get extracted.
1008 This is another reason why a task-based approach is preferred
1009 over a recipe-based approach, which would have to install the
1010 output from every task.
1011 </para>
1012 </section>
1013
1014 <section id='tips-and-tricks'>
1015 <title>Tips and Tricks</title>
1016
1017 <para>
1018 The code in the build system that supports incremental builds
1019 is not simple code.
1020 This section presents some tips and tricks that help you work
1021 around issues related to shared state code.
1022 </para>
1023
1024 <section id='overview-debugging'>
1025 <title>Debugging</title>
1026
1027 <para>
1028 Seeing what metadata went into creating the input signature
1029 of a shared state (sstate) task can be a useful debugging
1030 aid.
1031 This information is available in signature information
1032 (<filename>siginfo</filename>) files in
1033 <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>.
1034 For information on how to view and interpret information in
1035 <filename>siginfo</filename> files, see the
1036 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</ulink>"
1037 section in the Yocto Project Development Tasks Manual.
1038 </para>
1039 </section>
1040
1041 <section id='invalidating-shared-state'>
1042 <title>Invalidating Shared State</title>
1043
1044 <para>
1045 The OpenEmbedded build system uses checksums and shared
1046 state cache to avoid unnecessarily rebuilding tasks.
1047 Collectively, this scheme is known as "shared state code."
1048 </para>
1049
1050 <para>
1051 As with all schemes, this one has some drawbacks.
1052 It is possible that you could make implicit changes to your
1053 code that the checksum calculations do not take into
1054 account.
1055 These implicit changes affect a task's output but do not
1056 trigger the shared state code into rebuilding a recipe.
1057 Consider an example during which a tool changes its output.
1058 Assume that the output of <filename>rpmdeps</filename>
1059 changes.
1060 The result of the change should be that all the
1061 <filename>package</filename> and
1062 <filename>package_write_rpm</filename> shared state cache
1063 items become invalid.
1064 However, because the change to the output is
1065 external to the code and therefore implicit,
1066 the associated shared state cache items do not become
1067 invalidated.
1068 In this case, the build process uses the cached items
1069 rather than running the task again.
1070 Obviously, these types of implicit changes can cause
1071 problems.
1072 </para>
1073
1074 <para>
1075 To avoid these problems during the build, you need to
1076 understand the effects of any changes you make.
1077 Realize that changes you make directly to a function
1078 are automatically factored into the checksum calculation.
1079 Thus, these explicit changes invalidate the associated
1080 area of shared state cache.
1081 However, you need to be aware of any implicit changes that
1082 are not obvious changes to the code and could affect
1083 the output of a given task.
1084 </para>
1085
1086 <para>
1087 When you identify an implicit change, you can easily
1088 take steps to invalidate the cache and force the tasks
1089 to run.
1090 The steps you can take are as simple as changing a
1091 function's comments in the source code.
1092 For example, to invalidate package shared state files,
1093 change the comment statements of
1094 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
1095 or the comments of one of the functions it calls.
1096 Even though the change is purely cosmetic, it causes the
1097 checksum to be recalculated and forces the OpenEmbedded
1098 build system to run the task again.
1099 <note>
1100 For an example of a commit that makes a cosmetic
1101 change to invalidate shared state, see this
1102 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>.
1103 </note>
1104 </para>
1105 </section>
1106 </section>
1107 </section>
1108
1109 <section id='automatically-added-runtime-dependencies'>
1110 <title>Automatically Added Runtime Dependencies</title>
1111
1112 <para>
1113 The OpenEmbedded build system automatically adds common types of
1114 runtime dependencies between packages, which means that you do not
1115 need to explicitly declare the packages using
1116 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>.
1117 Three automatic mechanisms exist (<filename>shlibdeps</filename>,
1118 <filename>pcdeps</filename>, and <filename>depchains</filename>)
1119 that handle shared libraries, package configuration (pkg-config)
1120 modules, and <filename>-dev</filename> and
1121 <filename>-dbg</filename> packages, respectively.
1122 For other types of runtime dependencies, you must manually declare
1123 the dependencies.
1124 <itemizedlist>
1125 <listitem><para>
1126 <filename>shlibdeps</filename>:
1127 During the
1128 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
1129 task of each recipe, all shared libraries installed by the
1130 recipe are located.
1131 For each shared library, the package that contains the
1132 shared library is registered as providing the shared
1133 library.
1134 More specifically, the package is registered as providing
1135 the
1136 <ulink url='https://en.wikipedia.org/wiki/Soname'>soname</ulink>
1137 of the library.
1138 The resulting shared-library-to-package mapping
1139 is saved globally in
1140 <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink>
1141 by the
1142 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink>
1143 task.</para>
1144
1145 <para>Simultaneously, all executables and shared libraries
1146 installed by the recipe are inspected to see what shared
1147 libraries they link against.
1148 For each shared library dependency that is found,
1149 <filename>PKGDATA_DIR</filename> is queried to
1150 see if some package (likely from a different recipe)
1151 contains the shared library.
1152 If such a package is found, a runtime dependency is added
1153 from the package that depends on the shared library to the
1154 package that contains the library.</para>
1155
1156 <para>The automatically added runtime dependency also
1157 includes a version restriction.
1158 This version restriction specifies that at least the
1159 current version of the package that provides the shared
1160 library must be used, as if
1161 "<replaceable>package</replaceable> (>= <replaceable>version</replaceable>)"
1162 had been added to
1163 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>.
1164 This forces an upgrade of the package containing the shared
1165 library when installing the package that depends on the
1166 library, if needed.</para>
1167
1168 <para>If you want to avoid a package being registered as
1169 providing a particular shared library (e.g. because the library
1170 is for internal use only), then add the library to
1171 <ulink url='&YOCTO_DOCS_REF_URL;#var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></ulink>
1172 inside the package's recipe.
1173 </para></listitem>
1174 <listitem><para>
1175 <filename>pcdeps</filename>:
1176 During the
1177 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
1178 task of each recipe, all pkg-config modules
1179 (<filename>*.pc</filename> files) installed by the recipe
1180 are located.
1181 For each module, the package that contains the module is
1182 registered as providing the module.
1183 The resulting module-to-package mapping is saved globally in
1184 <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink>
1185 by the
1186 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink>
1187 task.</para>
1188
1189 <para>Simultaneously, all pkg-config modules installed by
1190 the recipe are inspected to see what other pkg-config
1191 modules they depend on.
1192 A module is seen as depending on another module if it
1193 contains a "Requires:" line that specifies the other module.
1194 For each module dependency,
1195 <filename>PKGDATA_DIR</filename> is queried to see if some
1196 package contains the module.
1197 If such a package is found, a runtime dependency is added
1198 from the package that depends on the module to the package
1199 that contains the module.
1200 <note>
1201 The <filename>pcdeps</filename> mechanism most often
1202 infers dependencies between <filename>-dev</filename>
1203 packages.
1204 </note>
1205 </para></listitem>
1206 <listitem><para>
1207 <filename>depchains</filename>:
1208 If a package <filename>foo</filename> depends on a package
1209 <filename>bar</filename>, then <filename>foo-dev</filename>
1210 and <filename>foo-dbg</filename> are also made to depend on
1211 <filename>bar-dev</filename> and
1212 <filename>bar-dbg</filename>, respectively.
1213 Taking the <filename>-dev</filename> packages as an
1214 example, the <filename>bar-dev</filename> package might
1215 provide headers and shared library symlinks needed by
1216 <filename>foo-dev</filename>, which shows the need
1217 for a dependency between the packages.</para>
1218
1219 <para>The dependencies added by
1220 <filename>depchains</filename> are in the form of
1221 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>.
1222 <note>
1223 By default, <filename>foo-dev</filename> also has an
1224 <filename>RDEPENDS</filename>-style dependency on
1225 <filename>foo</filename>, because the default value of
1226 <filename>RDEPENDS_${PN}-dev</filename> (set in
1227 <filename>bitbake.conf</filename>) includes
1228 "${PN}".
1229 </note></para>
1230
1231 <para>To ensure that the dependency chain is never broken,
1232 <filename>-dev</filename> and <filename>-dbg</filename>
1233 packages are always generated by default, even if the
1234 packages turn out to be empty.
1235 See the
1236 <ulink url='&YOCTO_DOCS_REF_URL;#var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></ulink>
1237 variable for more information.
1238 </para></listitem>
1239 </itemizedlist>
1240 </para>
1241
1242 <para>
1243 The <filename>do_package</filename> task depends on the
1244 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink>
1245 task of each recipe in
1246 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
1247 through use of a
1248 <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>deptask</filename></ulink><filename>]</filename>
1249 declaration, which guarantees that the required
1250 shared-library/module-to-package mapping information will be available
1251 when needed as long as <filename>DEPENDS</filename> has been
1252 correctly set.
1253 </para>
1254 </section>
1255
1256 <section id='fakeroot-and-pseudo'>
1257 <title>Fakeroot and Pseudo</title>
1258
1259 <para>
1260 Some tasks are easier to implement when allowed to perform certain
1261 operations that are normally reserved for the root user (e.g.
1262 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>,
1263 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb'><filename>do_package_write*</filename></ulink>,
1264 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-rootfs'><filename>do_rootfs</filename></ulink>,
1265 and
1266 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-image'><filename>do_image*</filename></ulink>).
1267 For example, the <filename>do_install</filename> task benefits
1268 from being able to set the UID and GID of installed files to
1269 arbitrary values.
1270 </para>
1271
1272 <para>
1273 One approach to allowing tasks to perform root-only operations
1274 would be to require BitBake to run as root.
1275 However, this method is cumbersome and has security issues.
1276 The approach that is actually used is to run tasks that benefit
1277 from root privileges in a "fake" root environment.
1278 Within this environment, the task and its child processes believe
1279 that they are running as the root user, and see an internally
1280 consistent view of the filesystem.
1281 As long as generating the final output (e.g. a package or an image)
1282 does not require root privileges, the fact that some earlier
1283 steps ran in a fake root environment does not cause problems.
1284 </para>
1285
1286 <para>
1287 The capability to run tasks in a fake root environment is known as
1288 "<ulink url='http://man.he.net/man1/fakeroot'>fakeroot</ulink>",
1289 which is derived from the BitBake keyword/variable
1290 flag that requests a fake root environment for a task.
1291 </para>
1292
1293 <para>
1294 In the OpenEmbedded build system, the program that implements
1295 fakeroot is known as Pseudo.
1296 Pseudo overrides system calls by using the environment variable
1297 <filename>LD_PRELOAD</filename>, which results in the illusion
1298 of running as root.
1299 To keep track of "fake" file ownership and permissions resulting
1300 from operations that require root permissions, Pseudo uses
1301 an SQLite 3 database.
1302 This database is stored in
1303 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/pseudo/files.db</filename>
1304 for individual recipes.
1305 Storing the database in a file as opposed to in memory
1306 gives persistence between tasks and builds, which is not
1307 accomplished using fakeroot.
1308 <note><title>Caution</title>
1309 If you add your own task that manipulates the same files or
1310 directories as a fakeroot task, then that task also needs to
1311 run under fakeroot.
1312 Otherwise, the task cannot run root-only operations, and
1313 cannot see the fake file ownership and permissions set by the
1314 other task.
1315 You need to also add a dependency on
1316 <filename>virtual/fakeroot-native:do_populate_sysroot</filename>,
1317 giving the following:
1318 <literallayout class='monospaced'>
1319 fakeroot do_mytask () {
1320 ...
1321 }
1322 do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot"
1323 </literallayout>
1324 </note>
1325 For more information, see the
1326 <ulink url='&YOCTO_DOCS_BB_URL;#var-FAKEROOT'><filename>FAKEROOT*</filename></ulink>
1327 variables in the BitBake User Manual.
1328 You can also reference the
1329 "<ulink url='http://www.ibm.com/developerworks/opensource/library/os-aapseudo1/index.html'>Pseudo</ulink>"
1330 and
1331 "<ulink url='https://github.com/wrpseudo/pseudo/wiki/WhyNotFakeroot'>Why Not Fakeroot?</ulink>"
1332 articles for background information on Pseudo.
1333 </para>
1334 </section>
1335
1336 <section id="wayland">
1337 <title>Wayland</title>
1338
1339 <para>
1340 <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)'>Wayland</ulink>
1341 is a computer display server protocol that
1342 provides a method for compositing window managers to communicate
1343 directly with applications and video hardware and expects them to
1344 communicate with input hardware using other libraries.
1345 Using Wayland with supporting targets can result in better control
1346 over graphics frame rendering than an application might otherwise
1347 achieve.
1348 </para>
1349
1350 <para>
1351 The Yocto Project provides the Wayland protocol libraries and the
1352 reference
1353 <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)#Weston'>Weston</ulink>
1354 compositor as part of its release.
1355 This section describes what you need to do to implement Wayland and
1356 use the compositor when building an image for a supporting target.
1357 </para>
1358
1359 <section id="wayland-support">
1360 <title>Support</title>
1361
1362 <para>
1363 The Wayland protocol libraries and the reference Weston
1364 compositor ship as integrated packages in the
1365 <filename>meta</filename> layer of the
1366 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
1367 Specifically, you can find the recipes that build both Wayland
1368 and Weston at
1369 <filename>meta/recipes-graphics/wayland</filename>.
1370 </para>
1371
1372 <para>
1373 You can build both the Wayland and Weston packages for use only
1374 with targets that accept the
1375 <ulink url='https://en.wikipedia.org/wiki/Mesa_(computer_graphics)'>Mesa 3D and Direct Rendering Infrastructure</ulink>,
1376 which is also known as Mesa DRI.
1377 This implies that you cannot build and use the packages if your
1378 target uses, for example, the
1379 <trademark class='registered'>Intel</trademark> Embedded Media
1380 and Graphics Driver
1381 (<trademark class='registered'>Intel</trademark> EMGD) that
1382 overrides Mesa DRI.
1383 <note>
1384 Due to lack of EGL support, Weston 1.0.3 will not run
1385 directly on the emulated QEMU hardware.
1386 However, this version of Weston will run under X emulation
1387 without issues.
1388 </note>
1389 </para>
1390 </section>
1391
1392 <section id="enabling-wayland-in-an-image">
1393 <title>Enabling Wayland in an Image</title>
1394
1395 <para>
1396 To enable Wayland, you need to enable it to be built and enable
1397 it to be included in the image.
1398 </para>
1399
1400 <section id="enable-building">
1401 <title>Building</title>
1402
1403 <para>
1404 To cause Mesa to build the <filename>wayland-egl</filename>
1405 platform and Weston to build Wayland with Kernel Mode
1406 Setting
1407 (<ulink url='https://wiki.archlinux.org/index.php/Kernel_Mode_Setting'>KMS</ulink>)
1408 support, include the "wayland" flag in the
1409 <ulink url="&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES"><filename>DISTRO_FEATURES</filename></ulink>
1410 statement in your <filename>local.conf</filename> file:
1411 <literallayout class='monospaced'>
1412 DISTRO_FEATURES_append = " wayland"
1413 </literallayout>
1414 <note>
1415 If X11 has been enabled elsewhere, Weston will build
1416 Wayland with X11 support
1417 </note>
1418 </para>
1419 </section>
1420
1421 <section id="enable-installation-in-an-image">
1422 <title>Installing</title>
1423
1424 <para>
1425 To install the Wayland feature into an image, you must
1426 include the following
1427 <ulink url='&YOCTO_DOCS_REF_URL;#var-CORE_IMAGE_EXTRA_INSTALL'><filename>CORE_IMAGE_EXTRA_INSTALL</filename></ulink>
1428 statement in your <filename>local.conf</filename> file:
1429 <literallayout class='monospaced'>
1430 CORE_IMAGE_EXTRA_INSTALL += "wayland weston"
1431 </literallayout>
1432 </para>
1433 </section>
1434 </section>
1435
1436 <section id="running-weston">
1437 <title>Running Weston</title>
1438
1439 <para>
1440 To run Weston inside X11, enabling it as described earlier and
1441 building a Sato image is sufficient.
1442 If you are running your image under Sato, a Weston Launcher
1443 appears in the "Utility" category.
1444 </para>
1445
1446 <para>
1447 Alternatively, you can run Weston through the command-line
1448 interpretor (CLI), which is better suited for development work.
1449 To run Weston under the CLI, you need to do the following after
1450 your image is built:
1451 <orderedlist>
1452 <listitem><para>
1453 Run these commands to export
1454 <filename>XDG_RUNTIME_DIR</filename>:
1455 <literallayout class='monospaced'>
1456 mkdir -p /tmp/$USER-weston
1457 chmod 0700 /tmp/$USER-weston
1458 export XDG_RUNTIME_DIR=/tmp/$USER-weston
1459 </literallayout>
1460 </para></listitem>
1461 <listitem><para>
1462 Launch Weston in the shell:
1463 <literallayout class='monospaced'>
1464 weston
1465 </literallayout></para></listitem>
1466 </orderedlist>
1467 </para>
1468 </section>
1469 </section>
1470
1471 <section id="overview-licenses">
1472 <title>Licenses</title>
1473
1474 <para>
1475 This section describes the mechanism by which the OpenEmbedded
1476 build system tracks changes to licensing text.
1477 The section also describes how to enable commercially licensed
1478 recipes, which by default are disabled.
1479 </para>
1480
1481 <para>
1482 For information that can help you maintain compliance with
1483 various open source licensing during the lifecycle of the product,
1484 see the
1485 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Project's Lifecycle</ulink>"
1486 section in the Yocto Project Development Tasks Manual.
1487 </para>
1488
1489 <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
1490 <title>Tracking License Changes</title>
1491
1492 <para>
1493 The license of an upstream project might change in the future.
1494 In order to prevent these changes going unnoticed, the
1495 <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
1496 variable tracks changes to the license text. The checksums are
1497 validated at the end of the configure step, and if the
1498 checksums do not match, the build will fail.
1499 </para>
1500
1501 <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
1502 <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
1503
1504 <para>
1505 The <filename>LIC_FILES_CHKSUM</filename>
1506 variable contains checksums of the license text in the
1507 source code for the recipe.
1508 Following is an example of how to specify
1509 <filename>LIC_FILES_CHKSUM</filename>:
1510 <literallayout class='monospaced'>
1511 LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
1512 file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
1513 file://licfile2.txt;endline=50;md5=zzzz \
1514 ..."
1515 </literallayout>
1516 <note><title>Notes</title>
1517 <itemizedlist>
1518 <listitem><para>
1519 When using "beginline" and "endline", realize
1520 that line numbering begins with one and not
1521 zero.
1522 Also, the included lines are inclusive (i.e.
1523 lines five through and including 29 in the
1524 previous example for
1525 <filename>licfile1.txt</filename>).
1526 </para></listitem>
1527 <listitem><para>
1528 When a license check fails, the selected license
1529 text is included as part of the QA message.
1530 Using this output, you can determine the exact
1531 start and finish for the needed license text.
1532 </para></listitem>
1533 </itemizedlist>
1534 </note>
1535 </para>
1536
1537 <para>
1538 The build system uses the
1539 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
1540 variable as the default directory when searching files
1541 listed in <filename>LIC_FILES_CHKSUM</filename>.
1542 The previous example employs the default directory.
1543 </para>
1544
1545 <para>
1546 Consider this next example:
1547 <literallayout class='monospaced'>
1548 LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\
1549 md5=bb14ed3c4cda583abc85401304b5cd4e"
1550 LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
1551 </literallayout>
1552 </para>
1553
1554 <para>
1555 The first line locates a file in
1556 <filename>${S}/src/ls.c</filename> and isolates lines five
1557 through 16 as license text.
1558 The second line refers to a file in
1559 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>.
1560 </para>
1561
1562 <para>
1563 Note that <filename>LIC_FILES_CHKSUM</filename> variable is
1564 mandatory for all recipes, unless the
1565 <filename>LICENSE</filename> variable is set to "CLOSED".
1566 </para>
1567 </section>
1568
1569 <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
1570 <title>Explanation of Syntax</title>
1571
1572 <para>
1573 As mentioned in the previous section, the
1574 <filename>LIC_FILES_CHKSUM</filename> variable lists all
1575 the important files that contain the license text for the
1576 source code.
1577 It is possible to specify a checksum for an entire file,
1578 or a specific section of a file (specified by beginning and
1579 ending line numbers with the "beginline" and "endline"
1580 parameters, respectively).
1581 The latter is useful for source files with a license
1582 notice header, README documents, and so forth.
1583 If you do not use the "beginline" parameter, then it is
1584 assumed that the text begins on the first line of the file.
1585 Similarly, if you do not use the "endline" parameter,
1586 it is assumed that the license text ends with the last
1587 line of the file.
1588 </para>
1589
1590 <para>
1591 The "md5" parameter stores the md5 checksum of the license
1592 text.
1593 If the license text changes in any way as compared to
1594 this parameter then a mismatch occurs.
1595 This mismatch triggers a build failure and notifies
1596 the developer.
1597 Notification allows the developer to review and address
1598 the license text changes.
1599 Also note that if a mismatch occurs during the build,
1600 the correct md5 checksum is placed in the build log and
1601 can be easily copied to the recipe.
1602 </para>
1603
1604 <para>
1605 There is no limit to how many files you can specify using
1606 the <filename>LIC_FILES_CHKSUM</filename> variable.
1607 Generally, however, every project requires a few
1608 specifications for license tracking.
1609 Many projects have a "COPYING" file that stores the
1610 license information for all the source code files.
1611 This practice allows you to just track the "COPYING"
1612 file as long as it is kept up to date.
1613 <note><title>Tips</title>
1614 <itemizedlist>
1615 <listitem><para>
1616 If you specify an empty or invalid "md5"
1617 parameter, BitBake returns an md5 mis-match
1618 error and displays the correct "md5" parameter
1619 value during the build.
1620 The correct parameter is also captured in
1621 the build log.
1622 </para></listitem>
1623 <listitem><para>
1624 If the whole file contains only license text,
1625 you do not need to use the "beginline" and
1626 "endline" parameters.
1627 </para></listitem>
1628 </itemizedlist>
1629 </note>
1630 </para>
1631 </section>
1632 </section>
1633
1634 <section id="enabling-commercially-licensed-recipes">
1635 <title>Enabling Commercially Licensed Recipes</title>
1636
1637 <para>
1638 By default, the OpenEmbedded build system disables
1639 components that have commercial or other special licensing
1640 requirements.
1641 Such requirements are defined on a
1642 recipe-by-recipe basis through the
1643 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
1644 variable definition in the affected recipe.
1645 For instance, the
1646 <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
1647 recipe contains the following statement:
1648 <literallayout class='monospaced'>
1649 LICENSE_FLAGS = "commercial"
1650 </literallayout>
1651 Here is a slightly more complicated example that contains both
1652 an explicit recipe name and version (after variable expansion):
1653 <literallayout class='monospaced'>
1654 LICENSE_FLAGS = "license_${PN}_${PV}"
1655 </literallayout>
1656 In order for a component restricted by a
1657 <filename>LICENSE_FLAGS</filename> definition to be enabled and
1658 included in an image, it needs to have a matching entry in the
1659 global
1660 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>
1661 variable, which is a variable typically defined in your
1662 <filename>local.conf</filename> file.
1663 For example, to enable the
1664 <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
1665 package, you could add either the string
1666 "commercial_gst-plugins-ugly" or the more general string
1667 "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>.
1668 See the
1669 "<link linkend='license-flag-matching'>License Flag Matching</link>"
1670 section for a full
1671 explanation of how <filename>LICENSE_FLAGS</filename> matching
1672 works.
1673 Here is the example:
1674 <literallayout class='monospaced'>
1675 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
1676 </literallayout>
1677 Likewise, to additionally enable the package built from the
1678 recipe containing
1679 <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>,
1680 and assuming that the actual recipe name was
1681 <filename>emgd_1.10.bb</filename>, the following string would
1682 enable that package as well as the original
1683 <filename>gst-plugins-ugly</filename> package:
1684 <literallayout class='monospaced'>
1685 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
1686 </literallayout>
1687 As a convenience, you do not need to specify the complete
1688 license string in the whitelist for every package.
1689 You can use an abbreviated form, which consists
1690 of just the first portion or portions of the license
1691 string before the initial underscore character or characters.
1692 A partial string will match any license that contains the
1693 given string as the first portion of its license.
1694 For example, the following whitelist string will also match
1695 both of the packages previously mentioned as well as any other
1696 packages that have licenses starting with "commercial" or
1697 "license".
1698 <literallayout class='monospaced'>
1699 LICENSE_FLAGS_WHITELIST = "commercial license"
1700 </literallayout>
1701 </para>
1702
1703 <section id="license-flag-matching">
1704 <title>License Flag Matching</title>
1705
1706 <para>
1707 License flag matching allows you to control what recipes
1708 the OpenEmbedded build system includes in the build.
1709 Fundamentally, the build system attempts to match
1710 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
1711 strings found in recipes against
1712 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>
1713 strings found in the whitelist.
1714 A match causes the build system to include a recipe in the
1715 build, while failure to find a match causes the build
1716 system to exclude a recipe.
1717 </para>
1718
1719 <para>
1720 In general, license flag matching is simple.
1721 However, understanding some concepts will help you
1722 correctly and effectively use matching.
1723 </para>
1724
1725 <para>
1726 Before a flag
1727 defined by a particular recipe is tested against the
1728 contents of the whitelist, the expanded string
1729 <filename>_${PN}</filename> is appended to the flag.
1730 This expansion makes each
1731 <filename>LICENSE_FLAGS</filename> value recipe-specific.
1732 After expansion, the string is then matched against the
1733 whitelist.
1734 Thus, specifying
1735 <filename>LICENSE_FLAGS = "commercial"</filename>
1736 in recipe "foo", for example, results in the string
1737 <filename>"commercial_foo"</filename>.
1738 And, to create a match, that string must appear in the
1739 whitelist.
1740 </para>
1741
1742 <para>
1743 Judicious use of the <filename>LICENSE_FLAGS</filename>
1744 strings and the contents of the
1745 <filename>LICENSE_FLAGS_WHITELIST</filename> variable
1746 allows you a lot of flexibility for including or excluding
1747 recipes based on licensing.
1748 For example, you can broaden the matching capabilities by
1749 using license flags string subsets in the whitelist.
1750 <note>
1751 When using a string subset, be sure to use the part of
1752 the expanded string that precedes the appended
1753 underscore character (e.g.
1754 <filename>usethispart_1.3</filename>,
1755 <filename>usethispart_1.4</filename>, and so forth).
1756 </note>
1757 For example, simply specifying the string "commercial" in
1758 the whitelist matches any expanded
1759 <filename>LICENSE_FLAGS</filename> definition that starts
1760 with the string "commercial" such as "commercial_foo" and
1761 "commercial_bar", which are the strings the build system
1762 automatically generates for hypothetical recipes named
1763 "foo" and "bar" assuming those recipes simply specify the
1764 following:
1765 <literallayout class='monospaced'>
1766 LICENSE_FLAGS = "commercial"
1767 </literallayout>
1768 Thus, you can choose to exhaustively
1769 enumerate each license flag in the whitelist and
1770 allow only specific recipes into the image, or
1771 you can use a string subset that causes a broader range of
1772 matches to allow a range of recipes into the image.
1773 </para>
1774
1775 <para>
1776 This scheme works even if the
1777 <filename>LICENSE_FLAGS</filename> string already
1778 has <filename>_${PN}</filename> appended.
1779 For example, the build system turns the license flag
1780 "commercial_1.2_foo" into "commercial_1.2_foo_foo" and
1781 would match both the general "commercial" and the specific
1782 "commercial_1.2_foo" strings found in the whitelist, as
1783 expected.
1784 </para>
1785
1786 <para>
1787 Here are some other scenarios:
1788 <itemizedlist>
1789 <listitem><para>
1790 You can specify a versioned string in the recipe
1791 such as "commercial_foo_1.2" in a "foo" recipe.
1792 The build system expands this string to
1793 "commercial_foo_1.2_foo".
1794 Combine this license flag with a whitelist that has
1795 the string "commercial" and you match the flag
1796 along with any other flag that starts with the
1797 string "commercial".
1798 </para></listitem>
1799 <listitem><para>
1800 Under the same circumstances, you can use
1801 "commercial_foo" in the whitelist and the build
1802 system not only matches "commercial_foo_1.2" but
1803 also matches any license flag with the string
1804 "commercial_foo", regardless of the version.
1805 </para></listitem>
1806 <listitem><para>
1807 You can be very specific and use both the
1808 package and version parts in the whitelist (e.g.
1809 "commercial_foo_1.2") to specifically match a
1810 versioned recipe.
1811 </para></listitem>
1812 </itemizedlist>
1813 </para>
1814 </section>
1815
1816 <section id="other-variables-related-to-commercial-licenses">
1817 <title>Other Variables Related to Commercial Licenses</title>
1818
1819 <para>
1820 Other helpful variables related to commercial
1821 license handling exist and are defined in the
1822 <filename>poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
1823 <literallayout class='monospaced'>
1824 COMMERCIAL_AUDIO_PLUGINS ?= ""
1825 COMMERCIAL_VIDEO_PLUGINS ?= ""
1826 </literallayout>
1827 If you want to enable these components, you can do so by
1828 making sure you have statements similar to the following
1829 in your <filename>local.conf</filename> configuration file:
1830 <literallayout class='monospaced'>
1831 COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
1832 gst-plugins-ugly-mpegaudioparse"
1833 COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
1834 gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
1835 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
1836 </literallayout>
1837 Of course, you could also create a matching whitelist
1838 for those components using the more general "commercial"
1839 in the whitelist, but that would also enable all the
1840 other packages with
1841 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
1842 containing "commercial", which you may or may not want:
1843 <literallayout class='monospaced'>
1844 LICENSE_FLAGS_WHITELIST = "commercial"
1845 </literallayout>
1846 </para>
1847
1848 <para>
1849 Specifying audio and video plug-ins as part of the
1850 <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and
1851 <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements
1852 (along with the enabling
1853 <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the
1854 plug-ins or components into built images, thus adding
1855 support for media formats or components.
1856 </para>
1857 </section>
1858 </section>
1859 </section>
1860
1861 <section id='x32'>
1862 <title>x32 psABI</title>
1863
1864 <para>
1865 x32 processor-specific Application Binary Interface
1866 (<ulink url='https://software.intel.com/en-us/node/628948'>x32 psABI</ulink>)
1867 is a native 32-bit processor-specific ABI for
1868 <trademark class='registered'>Intel</trademark> 64 (x86-64)
1869 architectures.
1870 An ABI defines the calling conventions between functions in a
1871 processing environment.
1872 The interface determines what registers are used and what the sizes are
1873 for various C data types.
1874 </para>
1875
1876 <para>
1877 Some processing environments prefer using 32-bit applications even
1878 when running on Intel 64-bit platforms.
1879 Consider the i386 psABI, which is a very old 32-bit ABI for Intel
1880 64-bit platforms.
1881 The i386 psABI does not provide efficient use and access of the
1882 Intel 64-bit processor resources, leaving the system underutilized.
1883 Now consider the x86_64 psABI.
1884 This ABI is newer and uses 64-bits for data sizes and program
1885 pointers.
1886 The extra bits increase the footprint size of the programs,
1887 libraries, and also increases the memory and file system size
1888 requirements.
1889 Executing under the x32 psABI enables user programs to utilize CPU
1890 and system resources more efficiently while keeping the memory
1891 footprint of the applications low.
1892 Extra bits are used for registers but not for addressing mechanisms.
1893 </para>
1894
1895 <para>
1896 The Yocto Project supports the final specifications of x32 psABI
1897 as follows:
1898 <itemizedlist>
1899 <listitem><para>
1900 You can create packages and images in x32 psABI format on
1901 x86_64 architecture targets.
1902 </para></listitem>
1903 <listitem><para>
1904 You can successfully build recipes with the x32 toolchain.
1905 </para></listitem>
1906 <listitem><para>
1907 You can create and boot
1908 <filename>core-image-minimal</filename> and
1909 <filename>core-image-sato</filename> images.
1910 </para></listitem>
1911 <listitem><para>
1912 RPM Package Manager (RPM) support exists for x32 binaries.
1913 </para></listitem>
1914 <listitem><para>
1915 Support for large images exists.
1916 </para></listitem>
1917 </itemizedlist>
1918 </para>
1919
1920 <para>
1921 For steps on how to use x32 psABI, see the
1922 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-x32-psabi'>Using x32 psABI</ulink>"
1923 section in the Yocto Project Development Tasks Manual.
1924 </para>
1925 </section>
1926</chapter>
1927<!--
1928vim: expandtab tw=80 ts=4
1929-->
diff --git a/documentation/getting-started/getting-started.xml b/documentation/getting-started/getting-started.xml
index 930a202e1a..9249bb5732 100644
--- a/documentation/getting-started/getting-started.xml
+++ b/documentation/getting-started/getting-started.xml
@@ -54,7 +54,7 @@
54 <itemizedlist> 54 <itemizedlist>
55 <listitem><para> 55 <listitem><para>
56 This version of the 56 This version of the
57 <emphasis>Yocto Project Overview Manual</emphasis> 57 <emphasis>Getting Started With Yocto Project Manual</emphasis>
58 is for the &YOCTO_DOC_VERSION; release of the 58 is for the &YOCTO_DOC_VERSION; release of the
59 Yocto Project. 59 Yocto Project.
60 To be sure you have the latest version of the manual 60 To be sure you have the latest version of the manual
@@ -86,8 +86,6 @@
86 86
87 <xi:include href="getting-started-development-environment.xml"/> 87 <xi:include href="getting-started-development-environment.xml"/>
88 88
89 <xi:include href="getting-started-concepts.xml"/>
90
91</book> 89</book>
92<!-- 90<!--
93vim: expandtab tw=80 ts=4 91vim: expandtab tw=80 ts=4
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-02-13 12:43:35 +0000