summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/technical-details.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/technical-details.xml')
-rw-r--r--documentation/ref-manual/technical-details.xml1335
1 files changed, 1335 insertions, 0 deletions
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
new file mode 100644
index 0000000000..be9c38709a
--- /dev/null
+++ b/documentation/ref-manual/technical-details.xml
@@ -0,0 +1,1335 @@
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='technical-details'>
6<title>Technical Details</title>
7
8 <para>
9 This chapter provides technical details for various parts of the Yocto Project.
10 Currently, topics include Yocto Project components,
11 shared state (sstate) cache, x32, and Licenses.
12 </para>
13
14<section id='usingpoky-components'>
15 <title>Yocto Project Components</title>
16
17 <para>
18 The BitBake task executor together with various types of configuration files form the
19 OpenEmbedded Core.
20 This section overviews these by describing what they are used for
21 and how they interact.
22 </para>
23
24 <para>
25 BitBake handles the parsing and execution of the data files.
26 The data itself is of various types:
27 <itemizedlist>
28 <listitem><para><emphasis>Recipes:</emphasis> Provides details about particular
29 pieces of software.</para></listitem>
30 <listitem><para><emphasis>Class Data:</emphasis> Abstracts common build
31 information (e.g. how to build a Linux kernel).</para></listitem>
32 <listitem><para><emphasis>Configuration Data:</emphasis> Defines machine-specific settings,
33 policy decisions, and so forth.
34 Configuration data acts as the glue to bind everything together.</para></listitem>
35 </itemizedlist>
36 For more information on data, see the
37 "<ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-terms'>Yocto Project Terms</ulink>"
38 section in the Yocto Project Development Manual.
39 </para>
40
41 <para>
42 BitBake knows how to combine multiple data sources together and refers to each data source
43 as a layer.
44 For information on layers, see the
45 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and
46 Creating Layers</ulink>" section of the Yocto Project Development Manual.
47 </para>
48
49 <para>
50 Following are some brief details on these core components.
51 For more detailed information on these components, see the
52 "<link linkend='ref-structure'>Source Directory Structure</link>" chapter.
53 </para>
54
55 <section id='usingpoky-components-bitbake'>
56 <title>BitBake</title>
57
58 <para>
59 BitBake is the tool at the heart of the OpenEmbedded build system
60 and is responsible for parsing the
61 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,
62 generating a list of tasks from it, and then executing those tasks.
63 To see a list of the options BitBake supports, use the following
64 help command:
65 <literallayout class='monospaced'>
66 $ bitbake --help
67 </literallayout>
68 </para>
69
70 <para>
71 The most common usage for BitBake is <filename>bitbake &lt;packagename&gt;</filename>, where
72 <filename>packagename</filename> is the name of the package you want to build
73 (referred to as the "target" in this manual).
74 The target often equates to the first part of a <filename>.bb</filename> filename.
75 So, to run the <filename>matchbox-desktop_1.2.3.bb</filename> file, you
76 might type the following:
77 <literallayout class='monospaced'>
78 $ bitbake matchbox-desktop
79 </literallayout>
80 Several different versions of <filename>matchbox-desktop</filename> might exist.
81 BitBake chooses the one selected by the distribution configuration.
82 You can get more details about how BitBake chooses between different
83 target versions and providers in the
84 "<link linkend='ref-bitbake-providers'>Preferences and Providers</link>" section.
85 </para>
86
87 <para>
88 BitBake also tries to execute any dependent tasks first.
89 So for example, before building <filename>matchbox-desktop</filename>, BitBake
90 would build a cross compiler and <filename>eglibc</filename> if they had not already
91 been built.
92 <note>This release of the Yocto Project does not support the <filename>glibc</filename>
93 GNU version of the Unix standard C library. By default, the OpenEmbedded build system
94 builds with <filename>eglibc</filename>.</note>
95 </para>
96
97 <para>
98 A useful BitBake option to consider is the <filename>-k</filename> or
99 <filename>--continue</filename> option.
100 This option instructs BitBake to try and continue processing the job as much
101 as possible even after encountering an error.
102 When an error occurs, the target that
103 failed and those that depend on it cannot be remade.
104 However, when you use this option other dependencies can still be processed.
105 </para>
106 </section>
107
108 <section id='usingpoky-components-metadata'>
109 <title>Metadata (Recipes)</title>
110
111 <para>
112 The <filename>.bb</filename> files are usually referred to as "recipes."
113 In general, a recipe contains information about a single piece of software.
114 The information includes the location from which to download the source patches
115 (if any are needed), which special configuration options to apply,
116 how to compile the source files, and how to package the compiled output.
117 </para>
118
119 <para>
120 The term "package" can also be used to describe recipes.
121 However, since the same word is used for the packaged output from the OpenEmbedded
122 build system (i.e. <filename>.ipk</filename> or <filename>.deb</filename> files),
123 this document avoids using the term "package" when referring to recipes.
124 </para>
125 </section>
126
127 <section id='usingpoky-components-classes'>
128 <title>Classes</title>
129
130 <para>
131 Class files (<filename>.bbclass</filename>) contain information that
132 is useful to share between
133 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> files.
134 An example is the Autotools class, which contains
135 common settings for any application that Autotools uses.
136 The "<link linkend='ref-classes'>Classes</link>" chapter provides details
137 about common classes and how to use them.
138 </para>
139 </section>
140
141 <section id='usingpoky-components-configuration'>
142 <title>Configuration</title>
143
144 <para>
145 The configuration files (<filename>.conf</filename>) define various configuration variables
146 that govern the OpenEmbedded build process.
147 These files fall into several areas that define machine configuration options,
148 distribution configuration options, compiler tuning options, general common configuration
149 options, and user configuration options in <filename>local.conf</filename>, which is found
150 in the
151 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
152 </para>
153 </section>
154</section>
155
156<section id="cross-development-toolchain-generation">
157 <title>Cross-Development Toolchain Generation</title>
158
159 <para>
160 The Yocto Project does most of the work for you when it comes to
161 creating
162 <ulink url='&YOCTO_DOCS_DEV_URL;#cross-development-toolchain'>cross-development toolchains</ulink>.
163 This section provides some technical background information on how
164 cross-development toolchains are created and used.
165 For more information on these toolchain, you can also see the
166 <ulink url='&YOCTO_DOCS_ADT_URL;'>the Yocto Project Application Developer's Guide</ulink>.
167 </para>
168
169 <para>
170 In the Yocto Project development environment, cross-development
171 toolchains are used to build the image and applications that run on the
172 target hardware.
173 With just a few commands, the OpenEmbedded build system creates
174 these necessary toolchains for you.
175 </para>
176
177 <para>
178 The following figure shows a high-level build environment regarding
179 toolchain construction and use.
180 </para>
181
182 <para>
183 <imagedata fileref="figures/cross-development-toolchains.png" width="8in" depth="6in" align="center" />
184 </para>
185
186 <para>
187 Most of the work occurs on the Build Host.
188 This is the machine used to build images and generally work within the
189 the Yocto Project environment.
190 When you run BitBake to create an image, the OpenEmbedded build system
191 uses the host <filename>gcc</filename> compiler to bootstrap a
192 cross-compiler named <filename>gcc-cross</filename>.
193 The <filename>gcc-cross</filename> compiler is what BitBake uses to
194 compile source files when creating the target image.
195 You can think of <filename>gcc-cross</filename> simply as an
196 automatically generated cross-compiler that is used internally within
197 BitBake only.
198 </para>
199
200 <para>
201 The chain of events that occurs when <filename>gcc-cross</filename> is
202 bootstrapped is as follows:
203 <literallayout class='monospaced'>
204 gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> eglibc-initial -> eglibc -> gcc-cross -> gcc-runtime
205 </literallayout>
206 <itemizedlist>
207 <listitem><para><filename>gcc</filename>:
208 The build host's GNU Compiler Collection (GCC).
209 </para></listitem>
210 <listitem><para><filename>binutils-cross</filename>:
211 The bare minimum binary utilities needed in order to run
212 the <filename>gcc-cross-initial</filename> phase of the
213 bootstrap operation.
214 </para></listitem>
215 <listitem><para><filename>gcc-cross-initial</filename>:
216 An early stage of the bootstrap process for creating
217 the cross-compiler.
218 This stage builds enough of the <filename>gcc-cross</filename>,
219 the C library, and other pieces needed to finish building the
220 final cross-compiler in later stages.
221 This tool is a "native" package (i.e. it is designed to run on
222 the build host).
223 </para></listitem>
224 <listitem><para><filename>linux-libc-headers</filename>:
225 Headers needed for the cross-compiler.
226 </para></listitem>
227 <listitem><para><filename>eglibc-initial</filename>:
228 An initial version of the Embedded GLIBC needed to bootstrap
229 <filename>eglibc</filename>.
230 </para></listitem>
231 <listitem><para><filename>gcc-cross</filename>:
232 The final stage of the bootstrap process for the
233 cross-compiler.
234 This stage results in the actual cross-compiler that
235 BitBake uses when it builds an image for a targeted
236 device.
237 <note>
238 If you are replacing this cross compiler toolchain
239 with a custom version, you must replace
240 <filename>gcc-cross</filename>.
241 </note>
242 This tool is also a "native" package (i.e. it is
243 designed to run on the build host).
244 </para></listitem>
245 <listitem><para><filename>gcc-runtime</filename>:
246 Runtime libraries resulting from the toolchain bootstrapping
247 process.
248 This tool produces a binary that consists of the
249 runtime libraries need for the targeted device.
250 </para></listitem>
251 </itemizedlist>
252 </para>
253
254 <para>
255 You can use the OpenEmbedded build system to build an installer for
256 the relocatable SDK used to develop applications.
257 When you run the installer, it installs the toolchain, which contains
258 the development tools (e.g., the
259 <filename>gcc-cross-canadian</filename>),
260 <filename>binutils-cross-canadian</filename>, and other
261 <filename>nativesdk-*</filename> tools you need to cross-compile and
262 test your software.
263 The figure shows the commands you use to easily build out this
264 toolchain.
265 This cross-development toolchain is built to execute on the
266 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
267 which might or might not be the same
268 machine as the Build Host.
269 <note>
270 If your target architecture is supported by the Yocto Project,
271 you can take advantage of pre-built images that ship with the
272 Yocto Project and already contain cross-development toolchain
273 installers.
274 </note>
275 </para>
276
277 <para>
278 Here is the bootstrap process for the relocatable toolchain:
279 <literallayout class='monospaced'>
280 gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> eglibc-initial -> nativesdk-eglibc -> gcc-crosssdk -> gcc-cross-canadian
281 </literallayout>
282 <itemizedlist>
283 <listitem><para><filename>gcc</filename>:
284 The build host's GNU Compiler Collection (GCC).
285 </para></listitem>
286 <listitem><para><filename>binutils-crosssdk</filename>:
287 The bare minimum binary utilities needed in order to run
288 the <filename>gcc-crosssdk-initial</filename> phase of the
289 bootstrap operation.
290 </para></listitem>
291 <listitem><para><filename>gcc-crosssdk-initial</filename>:
292 An early stage of the bootstrap process for creating
293 the cross-compiler.
294 This stage builds enough of the
295 <filename>gcc-crosssdk</filename> and supporting pieces so that
296 the final stage of the bootstrap process can produce the
297 finished cross-compiler.
298 This tool is a "native" binary that runs on the build host.
299 </para></listitem>
300 <listitem><para><filename>linux-libc-headers</filename>:
301 Headers needed for the cross-compiler.
302 </para></listitem>
303 <listitem><para><filename>eglibc-initial</filename>:
304 An initial version of the Embedded GLIBC needed to bootstrap
305 <filename>nativesdk-eglibc</filename>.
306 </para></listitem>
307 <listitem><para><filename>nativesdk-eglibc</filename>:
308 The Embedded GLIBC needed to bootstrap the
309 <filename>gcc-crosssdk</filename>.
310 </para></listitem>
311 <listitem><para><filename>gcc-crosssdk</filename>:
312 The final stage of the bootstrap process for the
313 relocatable cross-compiler.
314 The <filename>gcc-crosssdk</filename> is a transitory compiler
315 and never leaves the build host.
316 Its purpose is to help in the bootstrap process to create the
317 eventual relocatable <filename>gcc-cross-canadian</filename>
318 compiler, which is relocatable.
319 This tool is also a "native" package (i.e. it is
320 designed to run on the build host).
321 </para></listitem>
322 <listitem><para><filename>gcc-cross-canadian</filename>:
323 The final relocatable cross-compiler.
324 When run on the
325 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
326 this tool
327 produces executable code that runs on the target device.
328 </para></listitem>
329 </itemizedlist>
330 </para>
331</section>
332
333<section id="shared-state-cache">
334 <title>Shared State Cache</title>
335
336 <para>
337 By design, the OpenEmbedded build system builds everything from scratch unless
338 BitBake can determine that parts do not need to be rebuilt.
339 Fundamentally, building from scratch is attractive as it means all parts are
340 built fresh and there is no possibility of stale data causing problems.
341 When developers hit problems, they typically default back to building from scratch
342 so they know the state of things from the start.
343 </para>
344
345 <para>
346 Building an image from scratch is both an advantage and a disadvantage to the process.
347 As mentioned in the previous paragraph, building from scratch ensures that
348 everything is current and starts from a known state.
349 However, building from scratch also takes much longer as it generally means
350 rebuilding things that do not necessarily need rebuilt.
351 </para>
352
353 <para>
354 The Yocto Project implements shared state code that supports incremental builds.
355 The implementation of the shared state code answers the following questions that
356 were fundamental roadblocks within the OpenEmbedded incremental build support system:
357 <itemizedlist>
358 <listitem>What pieces of the system have changed and what pieces have not changed?</listitem>
359 <listitem>How are changed pieces of software removed and replaced?</listitem>
360 <listitem>How are pre-built components that do not need to be rebuilt from scratch
361 used when they are available?</listitem>
362 </itemizedlist>
363 </para>
364
365 <para>
366 For the first question, the build system detects changes in the "inputs" to a given task by
367 creating a checksum (or signature) of the task's inputs.
368 If the checksum changes, the system assumes the inputs have changed and the task needs to be
369 rerun.
370 For the second question, the shared state (sstate) code tracks which tasks add which output
371 to the build process.
372 This means the output from a given task can be removed, upgraded or otherwise manipulated.
373 The third question is partly addressed by the solution for the second question
374 assuming the build system can fetch the sstate objects from remote locations and
375 install them if they are deemed to be valid.
376 </para>
377
378 <note>
379 The OpenEmbedded build system does not maintain
380 <link linkend='var-PR'><filename>PR</filename></link> information
381 as part of the shared state packages.
382 Consequently, considerations exist that affect maintaining shared
383 state feeds.
384 For information on how the OpenEmbedded works with packages and can
385 track incrementing <filename>PR</filename> information, see the
386 "<ulink url='&YOCTO_DOCS_DEV_URL;#incrementing-a-package-revision-number'>Incrementing a Package Revision Number</ulink>"
387 section.
388 </note>
389
390 <para>
391 The rest of this section goes into detail about the overall incremental build
392 architecture, the checksums (signatures), shared state, and some tips and tricks.
393 </para>
394
395 <section id='overall-architecture'>
396 <title>Overall Architecture</title>
397
398 <para>
399 When determining what parts of the system need to be built, BitBake
400 uses a per-task basis and does not use a per-recipe basis.
401 You might wonder why using a per-task basis is preferred over a per-recipe basis.
402 To help explain, consider having the IPK packaging backend enabled and then switching to DEB.
403 In this case, <filename>do_install</filename> and <filename>do_package</filename>
404 output are still valid.
405 However, with a per-recipe approach, the build would not include the
406 <filename>.deb</filename> files.
407 Consequently, you would have to invalidate the whole build and rerun it.
408 Rerunning everything is not the best situation.
409 Also in this case, the core must be "taught" much about specific tasks.
410 This methodology does not scale well and does not allow users to easily add new tasks
411 in layers or as external recipes without touching the packaged-staging core.
412 </para>
413 </section>
414
415 <section id='checksums'>
416 <title>Checksums (Signatures)</title>
417
418 <para>
419 The shared state code uses a checksum, which is a unique signature of a task's
420 inputs, to determine if a task needs to be run again.
421 Because it is a change in a task's inputs that triggers a rerun, the process
422 needs to detect all the inputs to a given task.
423 For shell tasks, this turns out to be fairly easy because
424 the build process generates a "run" shell script for each task and
425 it is possible to create a checksum that gives you a good idea of when
426 the task's data changes.
427 </para>
428
429 <para>
430 To complicate the problem, there are things that should not be included in
431 the checksum.
432 First, there is the actual specific build path of a given task -
433 the <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
434 It does not matter if the working directory changes because it should not
435 affect the output for target packages.
436 Also, the build process has the objective of making native or cross packages relocatable.
437 The checksum therefore needs to exclude <filename>WORKDIR</filename>.
438 The simplistic approach for excluding the working directory is to set
439 <filename>WORKDIR</filename> to some fixed value and create the checksum
440 for the "run" script.
441 </para>
442
443 <para>
444 Another problem results from the "run" scripts containing functions that
445 might or might not get called.
446 The incremental build solution contains code that figures out dependencies
447 between shell functions.
448 This code is used to prune the "run" scripts down to the minimum set,
449 thereby alleviating this problem and making the "run" scripts much more
450 readable as a bonus.
451 </para>
452
453 <para>
454 So far we have solutions for shell scripts.
455 What about Python tasks?
456 The same approach applies even though these tasks are more difficult.
457 The process needs to figure out what variables a Python function accesses
458 and what functions it calls.
459 Again, the incremental build solution contains code that first figures out
460 the variable and function dependencies, and then creates a checksum for the data
461 used as the input to the task.
462 </para>
463
464 <para>
465 Like the <filename>WORKDIR</filename> case, situations exist where dependencies
466 should be ignored.
467 For these cases, you can instruct the build process to ignore a dependency
468 by using a line like the following:
469 <literallayout class='monospaced'>
470 PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
471 </literallayout>
472 This example ensures that the <filename>PACKAGE_ARCHS</filename> variable does not
473 depend on the value of <filename>MACHINE</filename>, even if it does reference it.
474 </para>
475
476 <para>
477 Equally, there are cases where we need to add dependencies BitBake is not able to find.
478 You can accomplish this by using a line like the following:
479 <literallayout class='monospaced'>
480 PACKAGE_ARCHS[vardeps] = "MACHINE"
481 </literallayout>
482 This example explicitly adds the <filename>MACHINE</filename> variable as a
483 dependency for <filename>PACKAGE_ARCHS</filename>.
484 </para>
485
486 <para>
487 Consider a case with in-line Python, for example, where BitBake is not
488 able to figure out dependencies.
489 When running in debug mode (i.e. using <filename>-DDD</filename>), BitBake
490 produces output when it discovers something for which it cannot figure out
491 dependencies.
492 The Yocto Project team has currently not managed to cover those dependencies
493 in detail and is aware of the need to fix this situation.
494 </para>
495
496 <para>
497 Thus far, this section has limited discussion to the direct inputs into a task.
498 Information based on direct inputs is referred to as the "basehash" in the
499 code.
500 However, there is still the question of a task's indirect inputs - the
501 things that were already built and present in the
502 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
503 The checksum (or signature) for a particular task needs to add the hashes
504 of all the tasks on which the particular task depends.
505 Choosing which dependencies to add is a policy decision.
506 However, the effect is to generate a master checksum that combines the basehash
507 and the hashes of the task's dependencies.
508 </para>
509
510 <para>
511 At the code level, there are a variety of ways both the basehash and the
512 dependent task hashes can be influenced.
513 Within the BitBake configuration file, we can give BitBake some extra information
514 to help it construct the basehash.
515 The following statements effectively result in a list of global variable
516 dependency excludes - variables never included in any checksum:
517 <literallayout class='monospaced'>
518 BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH"
519 BB_HASHBASE_WHITELIST += "DL_DIR SSTATE_DIR THISDIR FILESEXTRAPATHS"
520 BB_HASHBASE_WHITELIST += "FILE_DIRNAME HOME LOGNAME SHELL TERM USER"
521 BB_HASHBASE_WHITELIST += "FILESPATH USERNAME STAGING_DIR_HOST STAGING_DIR_TARGET"
522 </literallayout>
523 The previous example actually excludes
524 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
525 since it is actually constructed as a path within
526 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, which is on
527 the whitelist.
528 </para>
529
530 <para>
531 The rules for deciding which hashes of dependent tasks to include through
532 dependency chains are more complex and are generally accomplished with a
533 Python function.
534 The code in <filename>meta/lib/oe/sstatesig.py</filename> shows two examples
535 of this and also illustrates how you can insert your own policy into the system
536 if so desired.
537 This file defines the two basic signature generators <filename>OE-Core</filename>
538 uses: "OEBasic" and "OEBasicHash".
539 By default, there is a dummy "noop" signature handler enabled in BitBake.
540 This means that behavior is unchanged from previous versions.
541 <filename>OE-Core</filename> uses the "OEBasicHash" signature handler by default
542 through this setting in the <filename>bitbake.conf</filename> file:
543 <literallayout class='monospaced'>
544 BB_SIGNATURE_HANDLER ?= "OEBasicHash"
545 </literallayout>
546 The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> is the same as the
547 "OEBasic" version but adds the task hash to the stamp files.
548 This results in any
549 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
550 change that changes the task hash, automatically
551 causing the task to be run again.
552 This removes the need to bump <link linkend='var-PR'><filename>PR</filename></link>
553 values and changes to Metadata automatically ripple across the build.
554 </para>
555
556 <para>
557 It is also worth noting that the end result of these signature generators is to
558 make some dependency and hash information available to the build.
559 This information includes:
560 <literallayout class='monospaced'>
561 BB_BASEHASH_task-&lt;taskname&gt; - the base hashes for each task in the recipe
562 BB_BASEHASH_&lt;filename:taskname&gt; - the base hashes for each dependent task
563 BBHASHDEPS_&lt;filename:taskname&gt; - The task dependencies for each task
564 BB_TASKHASH - the hash of the currently running task
565 </literallayout>
566 </para>
567 </section>
568
569 <section id='shared-state'>
570 <title>Shared State</title>
571
572 <para>
573 Checksums and dependencies, as discussed in the previous section, solve half the
574 problem.
575 The other part of the problem is being able to use checksum information during the build
576 and being able to reuse or rebuild specific components.
577 </para>
578
579 <para>
580 The shared state class (<filename>sstate.bbclass</filename>)
581 is a relatively generic implementation of how to "capture" a snapshot of a given task.
582 The idea is that the build process does not care about the source of a task's output.
583 Output could be freshly built or it could be downloaded and unpacked from
584 somewhere - the build process does not need to worry about its source.
585 </para>
586
587 <para>
588 There are two types of output, one is just about creating a directory
589 in <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
590 A good example is the output of either <filename>do_install</filename> or
591 <filename>do_package</filename>.
592 The other type of output occurs when a set of data is merged into a shared directory
593 tree such as the sysroot.
594 </para>
595
596 <para>
597 The Yocto Project team has tried to keep the details of the implementation hidden in
598 <filename>sstate.bbclass</filename>.
599 From a user's perspective, adding shared state wrapping to a task
600 is as simple as this <filename>do_deploy</filename> example taken from
601 <filename>do_deploy.bbclass</filename>:
602 <literallayout class='monospaced'>
603 DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
604 SSTATETASKS += "do_deploy"
605 do_deploy[sstate-name] = "deploy"
606 do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"
607 do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"
608
609 python do_deploy_setscene () {
610 sstate_setscene(d)
611 }
612 addtask do_deploy_setscene
613 </literallayout>
614 In the example, we add some extra flags to the task, a name field ("deploy"), an
615 input directory where the task sends data, and the output
616 directory where the data from the task should eventually be copied.
617 We also add a <filename>_setscene</filename> variant of the task and add the task
618 name to the <filename>SSTATETASKS</filename> list.
619 </para>
620
621 <para>
622 If you have a directory whose contents you need to preserve, you can do this with
623 a line like the following:
624 <literallayout class='monospaced'>
625 do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
626 </literallayout>
627 This method, as well as the following example, also works for multiple directories.
628 <literallayout class='monospaced'>
629 do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
630 do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
631 do_package[sstate-lockfile] = "${PACKAGELOCK}"
632 </literallayout>
633 These methods also include the ability to take a lockfile when manipulating
634 shared state directory structures since some cases are sensitive to file
635 additions or removals.
636 </para>
637
638 <para>
639 Behind the scenes, the shared state code works by looking in
640 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> and
641 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
642 for shared state files.
643 Here is an example:
644 <literallayout class='monospaced'>
645 SSTATE_MIRRORS ?= "\
646 file://.* http://someserver.tld/share/sstate/PATH \n \
647 file://.* file:///some/local/dir/sstate/PATH"
648 </literallayout>
649 <note>
650 The shared state directory (<filename>SSTATE_DIR</filename>) is
651 organized into two-character subdirectories, where the subdirectory
652 names are based on the first two characters of the hash.
653 If the shared state directory structure for a mirror has the
654 same structure as <filename>SSTATE_DIR</filename>, you must
655 specify "PATH" as part of the URI to enable the build system
656 to map to the appropriate subdirectory.
657 </note>
658 </para>
659
660 <para>
661 The shared state package validity can be detected just by looking at the
662 filename since the filename contains the task checksum (or signature) as
663 described earlier in this section.
664 If a valid shared state package is found, the build process downloads it
665 and uses it to accelerate the task.
666 </para>
667
668 <para>
669 The build processes use the <filename>*_setscene</filename> tasks
670 for the task acceleration phase.
671 BitBake goes through this phase before the main execution code and tries
672 to accelerate any tasks for which it can find shared state packages.
673 If a shared state package for a task is available, the shared state
674 package is used.
675 This means the task and any tasks on which it is dependent are not
676 executed.
677 </para>
678
679 <para>
680 As a real world example, the aim is when building an IPK-based image,
681 only the <filename>do_package_write_ipk</filename> tasks would have their
682 shared state packages fetched and extracted.
683 Since the sysroot is not used, it would never get extracted.
684 This is another reason why a task-based approach is preferred over a
685 recipe-based approach, which would have to install the output from every task.
686 </para>
687 </section>
688
689 <section id='tips-and-tricks'>
690 <title>Tips and Tricks</title>
691
692 <para>
693 The code in the build system that supports incremental builds is not
694 simple code.
695 This section presents some tips and tricks that help you work around
696 issues related to shared state code.
697 </para>
698
699 <section id='debugging'>
700 <title>Debugging</title>
701
702 <para>
703 When things go wrong, debugging needs to be straightforward.
704 Because of this, the Yocto Project team included strong debugging
705 tools:
706 <itemizedlist>
707 <listitem><para>Whenever a shared state package is written out, so is a
708 corresponding <filename>.siginfo</filename> file.
709 This practice results in a pickled Python database of all
710 the metadata that went into creating the hash for a given shared state
711 package.</para></listitem>
712 <listitem><para>If you run BitBake with the <filename>--dump-signatures</filename>
713 (or <filename>-S</filename>) option, BitBake dumps out
714 <filename>.siginfo</filename> files in
715 the stamp directory for every task it would have executed instead of
716 building the specified target package.</para></listitem>
717 <listitem><para>There is a <filename>bitbake-diffsigs</filename> command that
718 can process <filename>.siginfo</filename> files.
719 If you specify one of these files, BitBake dumps out the dependency
720 information in the file.
721 If you specify two files, BitBake compares the two files and dumps out
722 the differences between the two.
723 This more easily helps answer the question of "What
724 changed between X and Y?"</para></listitem>
725 </itemizedlist>
726 </para>
727 </section>
728
729 <section id='invalidating-shared-state'>
730 <title>Invalidating Shared State</title>
731
732 <para>
733 The shared state code uses checksums and shared state
734 cache to avoid unnecessarily rebuilding tasks.
735 As with all schemes, this one has some drawbacks.
736 It is possible that you could make implicit changes that are not factored
737 into the checksum calculation, but do affect a task's output.
738 A good example is perhaps when a tool changes its output.
739 Assume that the output of <filename>rpmdeps</filename> needed to change.
740 The result of the change should be that all the
741 <filename>package</filename>, <filename>package_write_rpm</filename>,
742 and <filename>package_deploy-rpm</filename> shared state cache
743 items would become invalid.
744 But, because this is a change that is external to the code and therefore implicit,
745 the associated shared state cache items do not become invalidated.
746 In this case, the build process uses the cached items rather than running the
747 task again.
748 Obviously, these types of implicit changes can cause problems.
749 </para>
750
751 <para>
752 To avoid these problems during the build, you need to understand the effects of any
753 change you make.
754 Note that any changes you make directly to a function automatically are factored into
755 the checksum calculation and thus, will invalidate the associated area of sstate cache.
756 You need to be aware of any implicit changes that are not obvious changes to the
757 code and could affect the output of a given task.
758 Once you are aware of such changes, you can take steps to invalidate the cache
759 and force the tasks to run.
760 The steps to take are as simple as changing function's comments in the source code.
761 For example, to invalidate package shared state files, change the comment statements
762 of <filename>do_package</filename> or the comments of one of the functions it calls.
763 The change is purely cosmetic, but it causes the checksum to be recalculated and
764 forces the task to be run again.
765 </para>
766
767 <note>
768 For an example of a commit that makes a cosmetic change to invalidate
769 a shared state, see this
770 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>.
771 </note>
772 </section>
773 </section>
774</section>
775
776<section id='x32'>
777 <title>x32</title>
778
779 <para>
780 x32 is a processor-specific Application Binary Interface (psABI) for x86_64.
781 An ABI defines the calling conventions between functions in a processing environment.
782 The interface determines what registers are used and what the sizes are for various C data types.
783 </para>
784
785 <para>
786 Some processing environments prefer using 32-bit applications even when running
787 on Intel 64-bit platforms.
788 Consider the i386 psABI, which is a very old 32-bit ABI for Intel 64-bit platforms.
789 The i386 psABI does not provide efficient use and access of the Intel 64-bit processor resources,
790 leaving the system underutilized.
791 Now consider the x86_64 psABI.
792 This ABI is newer and uses 64-bits for data sizes and program pointers.
793 The extra bits increase the footprint size of the programs, libraries,
794 and also increases the memory and file system size requirements.
795 Executing under the x32 psABI enables user programs to utilize CPU and system resources
796 more efficiently while keeping the memory footprint of the applications low.
797 Extra bits are used for registers but not for addressing mechanisms.
798 </para>
799
800 <section id='support'>
801 <title>Support</title>
802
803 <para>
804 While the x32 psABI specifications are not fully finalized, this Yocto Project
805 release supports current development specifications of x32 psABI.
806 As of this release of the Yocto Project, x32 psABI support exists as follows:
807 <itemizedlist>
808 <listitem><para>You can create packages and images in x32 psABI format on x86_64 architecture targets.
809 </para></listitem>
810 <listitem><para>You can successfully build many recipes with the x32 toolchain.</para></listitem>
811 <listitem><para>You can create and boot <filename>core-image-minimal</filename> and
812 <filename>core-image-sato</filename> images.</para></listitem>
813 </itemizedlist>
814 </para>
815 </section>
816
817 <section id='stabilizing-and-completing-x32'>
818 <title>Stabilizing and Completing x32</title>
819
820 <para>
821 As of this Yocto Project release, the x32 psABI kernel and library
822 interfaces specifications are not finalized.
823 </para>
824
825 <para>
826 Future Plans for the x32 psABI in the Yocto Project include the following:
827 <itemizedlist>
828 <listitem><para>Enhance and fix the few remaining recipes so they
829 work with and support x32 toolchains.</para></listitem>
830 <listitem><para>Enhance RPM Package Manager (RPM) support for x32 binaries.</para></listitem>
831 <listitem><para>Support larger images.</para></listitem>
832 </itemizedlist>
833 </para>
834 </section>
835
836 <section id='using-x32-right-now'>
837 <title>Using x32 Right Now</title>
838
839 <para>
840 Follow these steps to use the x32 spABI:
841 <itemizedlist>
842 <listitem><para>Enable the x32 psABI tuning file for <filename>x86_64</filename>
843 machines by editing the <filename>conf/local.conf</filename> like this:
844 <literallayout class='monospaced'>
845 MACHINE = "qemux86-64"
846 DEFAULTTUNE = "x86-64-x32"
847 baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE', True) \
848 or 'INVALID'), True) or 'lib'}"
849 #MACHINE = "genericx86"
850 #DEFAULTTUNE = "core2-64-x32"
851 </literallayout></para></listitem>
852 <listitem><para>As usual, use BitBake to build an image that supports the x32 psABI.
853 Here is an example:
854 <literallayout class='monospaced'>
855 $ bitbake core-image-sato
856 </literallayout></para></listitem>
857 <listitem><para>As usual, run your image using QEMU:
858 <literallayout class='monospaced'>
859 $ runqemu qemux86-64 core-image-sato
860 </literallayout></para></listitem>
861 </itemizedlist>
862 </para>
863 </section>
864</section>
865
866<section id="wayland">
867 <title>Wayland</title>
868
869 <para>
870 <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)#Weston'>Wayland</ulink>
871 is a computer display server protocol that when implemented
872 provides a method for compositing window managers to communicate
873 directly with applications and video hardware and expects them to
874 communicate with input hardware using other libraries.
875 Using Wayland with supporting targets can result in better control
876 over graphics frame rendering than an application might otherwise
877 achieve.
878 </para>
879
880 <para>
881 The Yocto Project provides the Wayland protocol libraries and the
882 reference Weston compositor as part of it release.
883 This section describes what you need to do to implement Wayland and
884 use the compositor when building an image for a supporting target.
885 </para>
886
887 <section id="wayland-support">
888 <title>Support</title>
889
890 <para>
891 The Wayland protocol libraries and the reference Weston compositor
892 ship as integrated packages in the <filename>meta</filename> layer
893 of the
894 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
895 Specifically, you can find the recipes that build both Wayland
896 and Weston at <filename>meta/recipes-graphics/wayland</filename>.
897 </para>
898
899 <para>
900 You can build both the Wayland and Weston packages for use only
901 with targets that accept the
902 <ulink url='http://dri.freedesktop.org/wiki/'>Mesa 3D and Direct Rendering Infrastructure</ulink>,
903 which is also known as Mesa DRI.
904 This implies that you cannot build and use the packages if your
905 target uses, for example, the
906 <trademark class='registered'>Intel</trademark> Embedded Media and
907 Graphics Driver (<trademark class='registered'>Intel</trademark>
908 EMGD) that overrides Mesa DRI.
909 </para>
910
911 <note>
912 Due to lack of EGL support, Weston 1.0.3 will not run directly on
913 the emulated QEMU hardware.
914 However, this version of Weston will run under X emulation without
915 issues.
916 </note>
917 </section>
918
919 <section id="enabling-wayland-in-an-image">
920 <title>Enabling Wayland in an Image</title>
921
922 <para>
923 To enable Wayland, you need to enable it to be built and enable
924 it to be included in the image.
925 </para>
926
927 <section id="enable-building">
928 <title>Building</title>
929
930 <para>
931 To cause Mesa to build the <filename>wayland-egl</filename>
932 platform and Weston to build Wayland with Kernel Mode
933 Setting
934 (<ulink url='https://wiki.archlinux.org/index.php/Kernel_Mode_Setting'>KMS</ulink>)
935 support, include the "wayland" flag in the
936 <link linkend="var-DISTRO_FEATURES"><filename>DISTRO_FEATURES</filename></link>
937 statement in your <filename>local.conf</filename> file:
938 <literallayout class='monospaced'>
939 DISTRO_FEATURES_append = " wayland"
940 </literallayout>
941 </para>
942
943 <note>
944 If X11 has been enabled elsewhere, Weston will build Wayland
945 with X11 support
946 </note>
947 </section>
948
949 <section id="enable-installation-in-an-image">
950 <title>Installing</title>
951
952 <para>
953 To install the Wayland feature into an image, you must
954 include the following
955 <link linkend='var-CORE_IMAGE_EXTRA_INSTALL'><filename>CORE_IMAGE_EXTRA_INSTALL</filename></link>
956 statement in your <filename>local.conf</filename> file:
957 <literallayout class='monospaced'>
958 CORE_IMAGE_EXTRA_INSTALL += "wayland weston"
959 </literallayout>
960 </para>
961 </section>
962 </section>
963
964 <section id="running-weston">
965 <title>Running Weston</title>
966
967 <para>
968 To run Weston inside X11, enabling it as described earlier and
969 building a Sato image is sufficient.
970 If you are running your image under Sato, a Weston Launcher appears
971 in the "Utility" category.
972 </para>
973
974 <para>
975 Alternatively, you can run Weston through the command-line
976 interpretor (CLI), which is better suited for development work.
977 To run Weston under the CLI you need to do the following after
978 your image is built:
979 <orderedlist>
980 <listitem><para>Run these commands to export
981 <filename>XDG_RUNTIME_DIR</filename>:
982 <literallayout class='monospaced'>
983 mkdir -p /tmp/$USER-weston
984 chmod 0700 /tmp/$USER-weston
985 export XDG_RUNTIME_DIR=/tmp/$USER=weston
986 </literallayout></para></listitem>
987 <listitem><para>Launch Weston in the shell:
988 <literallayout class='monospaced'>
989 weston
990 </literallayout></para></listitem>
991 </orderedlist>
992 </para>
993 </section>
994</section>
995
996<section id="licenses">
997 <title>Licenses</title>
998
999 <para>
1000 This section describes the mechanism by which the OpenEmbedded build system
1001 tracks changes to licensing text.
1002 The section also describes how to enable commercially licensed recipes,
1003 which by default are disabled.
1004 </para>
1005
1006 <para>
1007 For information that can help you maintain compliance with various open
1008 source licensing during the lifecycle of the product, see the
1009 "<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>" section
1010 in the Yocto Project Development Manual.
1011 </para>
1012
1013 <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
1014 <title>Tracking License Changes</title>
1015
1016 <para>
1017 The license of an upstream project might change in the future.
1018 In order to prevent these changes going unnoticed, the
1019 <filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></filename>
1020 variable tracks changes to the license text. The checksums are validated at the end of the
1021 configure step, and if the checksums do not match, the build will fail.
1022 </para>
1023
1024 <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
1025 <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
1026
1027 <para>
1028 The <filename>LIC_FILES_CHKSUM</filename>
1029 variable contains checksums of the license text in the source code for the recipe.
1030 Following is an example of how to specify <filename>LIC_FILES_CHKSUM</filename>:
1031 <literallayout class='monospaced'>
1032 LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
1033 file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
1034 file://licfile2.txt;endline=50;md5=zzzz \
1035 ..."
1036 </literallayout>
1037 </para>
1038
1039 <para>
1040 The build system uses the
1041 <filename><link linkend='var-S'>S</link></filename> variable as
1042 the default directory used when searching files listed in
1043 <filename>LIC_FILES_CHKSUM</filename>.
1044 The previous example employs the default directory.
1045 </para>
1046
1047 <para>
1048 Consider this next example:
1049 <literallayout class='monospaced'>
1050 LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\
1051 md5=bb14ed3c4cda583abc85401304b5cd4e"
1052 LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
1053 </literallayout>
1054 </para>
1055
1056 <para>
1057 The first line locates a file in
1058 <filename>${S}/src/ls.c</filename>.
1059 The second line refers to a file in
1060 <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>.
1061 </para>
1062 <para>
1063 Note that <filename>LIC_FILES_CHKSUM</filename> variable is
1064 mandatory for all recipes, unless the
1065 <filename>LICENSE</filename> variable is set to "CLOSED".
1066 </para>
1067 </section>
1068
1069 <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
1070 <title>Explanation of Syntax</title>
1071 <para>
1072 As mentioned in the previous section, the
1073 <filename>LIC_FILES_CHKSUM</filename> variable lists all the
1074 important files that contain the license text for the source code.
1075 It is possible to specify a checksum for an entire file, or a specific section of a
1076 file (specified by beginning and ending line numbers with the "beginline" and "endline"
1077 parameters, respectively).
1078 The latter is useful for source files with a license notice header,
1079 README documents, and so forth.
1080 If you do not use the "beginline" parameter, then it is assumed that the text begins on the
1081 first line of the file.
1082 Similarly, if you do not use the "endline" parameter, it is assumed that the license text
1083 ends with the last line of the file.
1084 </para>
1085
1086 <para>
1087 The "md5" parameter stores the md5 checksum of the license text.
1088 If the license text changes in any way as compared to this parameter
1089 then a mismatch occurs.
1090 This mismatch triggers a build failure and notifies the developer.
1091 Notification allows the developer to review and address the license text changes.
1092 Also note that if a mismatch occurs during the build, the correct md5
1093 checksum is placed in the build log and can be easily copied to the recipe.
1094 </para>
1095
1096 <para>
1097 There is no limit to how many files you can specify using the
1098 <filename>LIC_FILES_CHKSUM</filename> variable.
1099 Generally, however, every project requires a few specifications for license tracking.
1100 Many projects have a "COPYING" file that stores the license information for all the source
1101 code files.
1102 This practice allows you to just track the "COPYING" file as long as it is kept up to date.
1103 </para>
1104
1105 <tip>
1106 If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match
1107 error and displays the correct "md5" parameter value during the build.
1108 The correct parameter is also captured in the build log.
1109 </tip>
1110
1111 <tip>
1112 If the whole file contains only license text, you do not need to use the "beginline" and
1113 "endline" parameters.
1114 </tip>
1115 </section>
1116 </section>
1117
1118 <section id="enabling-commercially-licensed-recipes">
1119 <title>Enabling Commercially Licensed Recipes</title>
1120
1121 <para>
1122 By default, the OpenEmbedded build system disables
1123 components that have commercial or other special licensing
1124 requirements.
1125 Such requirements are defined on a
1126 recipe-by-recipe basis through the <filename>LICENSE_FLAGS</filename> variable
1127 definition in the affected recipe.
1128 For instance, the
1129 <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
1130 recipe contains the following statement:
1131 <literallayout class='monospaced'>
1132 LICENSE_FLAGS = "commercial"
1133 </literallayout>
1134 Here is a slightly more complicated example that contains both an
1135 explicit recipe name and version (after variable expansion):
1136 <literallayout class='monospaced'>
1137 LICENSE_FLAGS = "license_${PN}_${PV}"
1138 </literallayout>
1139 In order for a component restricted by a <filename>LICENSE_FLAGS</filename>
1140 definition to be enabled and included in an image, it
1141 needs to have a matching entry in the global
1142 <filename>LICENSE_FLAGS_WHITELIST</filename> variable, which is a variable
1143 typically defined in your <filename>local.conf</filename> file.
1144 For example, to enable
1145 the <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
1146 package, you could add either the string
1147 "commercial_gst-plugins-ugly" or the more general string
1148 "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>.
1149 See the
1150 "<link linkend='license-flag-matching'>License Flag Matching</link>" section
1151 for a full explanation of how <filename>LICENSE_FLAGS</filename> matching works.
1152 Here is the example:
1153 <literallayout class='monospaced'>
1154 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
1155 </literallayout>
1156 Likewise, to additionally enable the package built from the recipe containing
1157 <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>, and assuming
1158 that the actual recipe name was <filename>emgd_1.10.bb</filename>,
1159 the following string would enable that package as well as
1160 the original <filename>gst-plugins-ugly</filename> package:
1161 <literallayout class='monospaced'>
1162 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
1163 </literallayout>
1164 As a convenience, you do not need to specify the complete license string
1165 in the whitelist for every package.
1166 you can use an abbreviated form, which consists
1167 of just the first portion or portions of the license string before
1168 the initial underscore character or characters.
1169 A partial string will match
1170 any license that contains the given string as the first
1171 portion of its license.
1172 For example, the following
1173 whitelist string will also match both of the packages
1174 previously mentioned as well as any other packages that have
1175 licenses starting with "commercial" or "license".
1176 <literallayout class='monospaced'>
1177 LICENSE_FLAGS_WHITELIST = "commercial license"
1178 </literallayout>
1179 </para>
1180
1181 <section id="license-flag-matching">
1182 <title>License Flag Matching</title>
1183
1184 <para>
1185 License flag matching allows you to control what recipes the
1186 OpenEmbedded build system includes in the build.
1187 Fundamentally, the build system attempts to match
1188 <filename>LICENSE_FLAG</filename> strings found in
1189 recipes against <filename>LICENSE_FLAGS_WHITELIST</filename>
1190 strings found in the whitelist.
1191 A match, causes the build system to include a recipe in the
1192 build, while failure to find a match causes the build system to
1193 exclude a recipe.
1194 </para>
1195
1196 <para>
1197 In general, license flag matching is simple.
1198 However, understanding some concepts will help you
1199 correctly and effectively use matching.
1200 </para>
1201
1202 <para>
1203 Before a flag
1204 defined by a particular recipe is tested against the
1205 contents of the whitelist, the expanded string
1206 <filename>_${PN}</filename> is appended to the flag.
1207 This expansion makes each <filename>LICENSE_FLAGS</filename>
1208 value recipe-specific.
1209 After expansion, the string is then matched against the
1210 whitelist.
1211 Thus, specifying
1212 <filename>LICENSE_FLAGS = "commercial"</filename>
1213 in recipe "foo", for example, results in the string
1214 <filename>"commercial_foo"</filename>.
1215 And, to create a match, that string must appear in the
1216 whitelist.
1217 </para>
1218
1219 <para>
1220 Judicious use of the <filename>LICENSE_FLAGS</filename>
1221 strings and the contents of the
1222 <filename>LICENSE_FLAGS_WHITELIST</filename> variable
1223 allows you a lot of flexibility for including or excluding
1224 recipes based on licensing.
1225 For example, you can broaden the matching capabilities by
1226 using license flags string subsets in the whitelist.
1227 <note>When using a string subset, be sure to use the part of
1228 the expanded string that precedes the appended underscore
1229 character (e.g. <filename>usethispart_1.3</filename>,
1230 <filename>usethispart_1.4</filename>, and so forth).
1231 </note>
1232 For example, simply specifying the string "commercial" in
1233 the whitelist matches any expanded
1234 <filename>LICENSE_FLAGS</filename> definition that starts with
1235 the string "commercial" such as "commercial_foo" and
1236 "commercial_bar", which are the strings the build system
1237 automatically generates for hypothetical recipes named
1238 "foo" and "bar" assuming those recipes simply specify the
1239 following:
1240 <literallayout class='monospaced'>
1241 LICENSE_FLAGS = "commercial"
1242 </literallayout>
1243 Thus, you can choose to exhaustively
1244 enumerate each license flag in the whitelist and
1245 allow only specific recipes into the image, or
1246 you can use a string subset that causes a broader range of
1247 matches to allow a range of recipes into the image.
1248 </para>
1249
1250 <para>
1251 This scheme works even if the
1252 <filename>LICENSE_FLAG</filename> string already
1253 has <filename>_${PN}</filename> appended.
1254 For example, the build system turns the license flag
1255 "commercial_1.2_foo" into "commercial_1.2_foo_foo" and would
1256 match both the general "commercial" and the specific
1257 "commercial_1.2_foo" strings found in the whitelist, as
1258 expected.
1259 </para>
1260
1261 <para>
1262 Here are some other scenarios:
1263 <itemizedlist>
1264 <listitem><para>You can specify a versioned string in the
1265 recipe such as "commercial_foo_1.2" in a "foo" recipe.
1266 The build system expands this string to
1267 "commercial_foo_1.2_foo".
1268 Combine this license flag with a whitelist that has
1269 the string "commercial" and you match the flag along
1270 with any other flag that starts with the string
1271 "commercial".</para></listitem>
1272 <listitem><para>Under the same circumstances, you can
1273 use "commercial_foo" in the whitelist and the
1274 build system not only matches "commercial_foo_1.2" but
1275 also matches any license flag with the string
1276 "commercial_foo", regardless of the version.
1277 </para></listitem>
1278 <listitem><para>You can be very specific and use both the
1279 package and version parts in the whitelist (e.g.
1280 "commercial_foo_1.2") to specifically match a
1281 versioned recipe.</para></listitem>
1282 </itemizedlist>
1283 </para>
1284 </section>
1285
1286 <section id="other-variables-related-to-commercial-licenses">
1287 <title>Other Variables Related to Commercial Licenses</title>
1288
1289 <para>
1290 Other helpful variables related to commercial
1291 license handling exist and are defined in the
1292 <filename>$HOME/poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
1293 <literallayout class='monospaced'>
1294 COMMERCIAL_AUDIO_PLUGINS ?= ""
1295 COMMERCIAL_VIDEO_PLUGINS ?= ""
1296 COMMERCIAL_QT = ""
1297 </literallayout>
1298 If you want to enable these components, you can do so by making sure you have
1299 statements similar to the following
1300 in your <filename>local.conf</filename> configuration file:
1301 <literallayout class='monospaced'>
1302 COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
1303 gst-plugins-ugly-mpegaudioparse"
1304 COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
1305 gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
1306 COMMERCIAL_QT ?= "qmmp"
1307 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
1308 </literallayout>
1309 Of course, you could also create a matching whitelist
1310 for those components using the more general "commercial"
1311 in the whitelist, but that would also enable all the
1312 other packages with <filename>LICENSE_FLAGS</filename> containing
1313 "commercial", which you may or may not want:
1314 <literallayout class='monospaced'>
1315 LICENSE_FLAGS_WHITELIST = "commercial"
1316 </literallayout>
1317 </para>
1318
1319 <para>
1320 Specifying audio and video plug-ins as part of the
1321 <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and
1322 <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements
1323 or commercial Qt components as part of
1324 the <filename>COMMERCIAL_QT</filename> statement (along
1325 with the enabling <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the
1326 plug-ins or components into built images, thus adding
1327 support for media formats or components.
1328 </para>
1329 </section>
1330 </section>
1331</section>
1332</chapter>
1333<!--
1334vim: expandtab tw=80 ts=4
1335-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-04-23 15:09:54 +0000