summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/ref-manual/technical-details.xml84
1 files changed, 44 insertions, 40 deletions
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index f4f432f928..f863c4cfb7 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -60,9 +60,9 @@
60 and is responsible for parsing the 60 and is responsible for parsing the
61 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>, 61 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,
62 generating a list of tasks from it, and then executing those tasks. 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 63 To see a list of the options BitBake supports, use either of:
64 help command:
65 <literallayout class='monospaced'> 64 <literallayout class='monospaced'>
65 $ bitbake -h
66 $ bitbake --help 66 $ bitbake --help
67 </literallayout> 67 </literallayout>
68 </para> 68 </para>
@@ -72,7 +72,7 @@
72 <filename>packagename</filename> is the name of the package you want to build 72 <filename>packagename</filename> is the name of the package you want to build
73 (referred to as the "target" in this manual). 73 (referred to as the "target" in this manual).
74 The target often equates to the first part of a <filename>.bb</filename> filename. 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 75 So, to process the <filename>matchbox-desktop_1.2.3.bb</filename> recipe file, you
76 might type the following: 76 might type the following:
77 <literallayout class='monospaced'> 77 <literallayout class='monospaced'>
78 $ bitbake matchbox-desktop 78 $ bitbake matchbox-desktop
@@ -111,14 +111,15 @@
111 <para> 111 <para>
112 The <filename>.bb</filename> files are usually referred to as "recipes." 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. 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 114 This information includes the location from which to download the
115 pristine source, any source patches to be applied to that source
115 (if any are needed), which special configuration options to apply, 116 (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 how to compile the source files, and how to package the compiled output.
117 </para> 118 </para>
118 119
119 <para> 120 <para>
120 The term "package" can also be used to describe recipes. 121 The term "package" is sometimes (confusingly) used to refer to recipes. However,
121 However, since the same word is used for the packaged output from the OpenEmbedded 122 since the word "package" is used for the packaged output from the OpenEmbedded
122 build system (i.e. <filename>.ipk</filename> or <filename>.deb</filename> files), 123 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 this document avoids using the term "package" when referring to recipes.
124 </para> 125 </para>
@@ -162,7 +163,7 @@
162 <ulink url='&YOCTO_DOCS_DEV_URL;#cross-development-toolchain'>cross-development toolchains</ulink>. 163 <ulink url='&YOCTO_DOCS_DEV_URL;#cross-development-toolchain'>cross-development toolchains</ulink>.
163 This section provides some technical background information on how 164 This section provides some technical background information on how
164 cross-development toolchains are created and used. 165 cross-development toolchains are created and used.
165 For more information on these toolchain, you can also see the 166 For more information on toolchains, you can also see the
166 <ulink url='&YOCTO_DOCS_ADT_URL;'>the Yocto Project Application Developer's Guide</ulink>. 167 <ulink url='&YOCTO_DOCS_ADT_URL;'>the Yocto Project Application Developer's Guide</ulink>.
167 </para> 168 </para>
168 169
@@ -347,7 +348,7 @@
347 As mentioned in the previous paragraph, building from scratch ensures that 348 As mentioned in the previous paragraph, building from scratch ensures that
348 everything is current and starts from a known state. 349 everything is current and starts from a known state.
349 However, building from scratch also takes much longer as it generally means 350 However, building from scratch also takes much longer as it generally means
350 rebuilding things that do not necessarily need rebuilt. 351 rebuilding things that do not necessarily need to be rebuilt.
351 </para> 352 </para>
352 353
353 <para> 354 <para>
@@ -355,10 +356,11 @@
355 The implementation of the shared state code answers the following questions that 356 The implementation of the shared state code answers the following questions that
356 were fundamental roadblocks within the OpenEmbedded incremental build support system: 357 were fundamental roadblocks within the OpenEmbedded incremental build support system:
357 <itemizedlist> 358 <itemizedlist>
358 <listitem>What pieces of the system have changed and what pieces have not changed?</listitem> 359 <listitem><para>What pieces of the system have changed and what pieces have
359 <listitem>How are changed pieces of software removed and replaced?</listitem> 360 not changed?</para></listitem>
360 <listitem>How are pre-built components that do not need to be rebuilt from scratch 361 <listitem><para>How are changed pieces of software removed and replaced?</para></listitem>
361 used when they are available?</listitem> 362 <listitem><para>How are pre-built components that do not need to be rebuilt from scratch
363 used when they are available?</para></listitem>
362 </itemizedlist> 364 </itemizedlist>
363 </para> 365 </para>
364 366
@@ -397,16 +399,16 @@
397 399
398 <para> 400 <para>
399 When determining what parts of the system need to be built, BitBake 401 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. 402 works on a per-task basis rather than a per-recipe basis.
401 You might wonder why using a per-task basis is preferred over a per-recipe basis. 403 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. 404 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> 405 In this case, <filename>do_install</filename> and <filename>do_package</filename>
404 output are still valid. 406 outputs are still valid.
405 However, with a per-recipe approach, the build would not include the 407 However, with a per-recipe approach, the build would not include the
406 <filename>.deb</filename> files. 408 <filename>.deb</filename> files.
407 Consequently, you would have to invalidate the whole build and rerun it. 409 Consequently, you would have to invalidate the whole build and rerun it.
408 Rerunning everything is not the best situation. 410 Rerunning everything is not the best solution.
409 Also in this case, the core must be "taught" much about specific tasks. 411 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 412 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. 413 in layers or as external recipes without touching the packaged-staging core.
412 </para> 414 </para>
@@ -512,17 +514,18 @@
512 dependent task hashes can be influenced. 514 dependent task hashes can be influenced.
513 Within the BitBake configuration file, we can give BitBake some extra information 515 Within the BitBake configuration file, we can give BitBake some extra information
514 to help it construct the basehash. 516 to help it construct the basehash.
515 The following statements effectively result in a list of global variable 517 The following statement effectively results in a list of global variable
516 dependency excludes - variables never included in any checksum: 518 dependency excludes - variables never included in any checksum:
517 <literallayout class='monospaced'> 519 <literallayout class='monospaced'>
518 BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH" 520 BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \
519 BB_HASHBASE_WHITELIST += "DL_DIR SSTATE_DIR THISDIR FILESEXTRAPATHS" 521 SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \
520 BB_HASHBASE_WHITELIST += "FILE_DIRNAME HOME LOGNAME SHELL TERM USER" 522 USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \
521 BB_HASHBASE_WHITELIST += "FILESPATH USERNAME STAGING_DIR_HOST STAGING_DIR_TARGET" 523 PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \
524 CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX"
522 </literallayout> 525 </literallayout>
523 The previous example actually excludes 526 The previous example excludes
524 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link> 527 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
525 since it is actually constructed as a path within 528 since that variable is actually constructed as a path within
526 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, which is on 529 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, which is on
527 the whitelist. 530 the whitelist.
528 </para> 531 </para>
@@ -541,7 +544,7 @@
541 <filename>OE-Core</filename> uses the "OEBasicHash" signature handler by default 544 <filename>OE-Core</filename> uses the "OEBasicHash" signature handler by default
542 through this setting in the <filename>bitbake.conf</filename> file: 545 through this setting in the <filename>bitbake.conf</filename> file:
543 <literallayout class='monospaced'> 546 <literallayout class='monospaced'>
544 BB_SIGNATURE_HANDLER ?= "OEBasicHash" 547 BB_SIGNATURE_HANDLER ?= "OEBasicHash"
545 </literallayout> 548 </literallayout>
546 The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> is the same as the 549 The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> is the same as the
547 "OEBasic" version but adds the task hash to the stamp files. 550 "OEBasic" version but adds the task hash to the stamp files.
@@ -550,7 +553,7 @@
550 change that changes the task hash, automatically 553 change that changes the task hash, automatically
551 causing the task to be run again. 554 causing the task to be run again.
552 This removes the need to bump <link linkend='var-PR'><filename>PR</filename></link> 555 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. 556 values, and changes to Metadata automatically ripple across the build.
554 </para> 557 </para>
555 558
556 <para> 559 <para>
@@ -558,10 +561,10 @@
558 make some dependency and hash information available to the build. 561 make some dependency and hash information available to the build.
559 This information includes: 562 This information includes:
560 <literallayout class='monospaced'> 563 <literallayout class='monospaced'>
561 BB_BASEHASH_task-&lt;taskname&gt; - the base hashes for each task in the recipe 564 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 565 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 566 BBHASHDEPS_&lt;filename:taskname&gt; - The task dependencies for each task
564 BB_TASKHASH - the hash of the currently running task 567 BB_TASKHASH - the hash of the currently running task
565 </literallayout> 568 </literallayout>
566 </para> 569 </para>
567 </section> 570 </section>
@@ -571,7 +574,7 @@
571 574
572 <para> 575 <para>
573 Checksums and dependencies, as discussed in the previous section, solve half the 576 Checksums and dependencies, as discussed in the previous section, solve half the
574 problem. 577 problem of supporting a shared state.
575 The other part of the problem is being able to use checksum information during the build 578 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. 579 and being able to reuse or rebuild specific components.
577 </para> 580 </para>
@@ -581,7 +584,7 @@
581 is a relatively generic implementation of how to "capture" a snapshot of a given task. 584 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. 585 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 586 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. 587 somewhere - the build process does not need to worry about its origin.
585 </para> 588 </para>
586 589
587 <para> 590 <para>
@@ -598,7 +601,7 @@
598 <filename>sstate.bbclass</filename>. 601 <filename>sstate.bbclass</filename>.
599 From a user's perspective, adding shared state wrapping to a task 602 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 603 is as simple as this <filename>do_deploy</filename> example taken from
601 <filename>do_deploy.bbclass</filename>: 604 <filename>deploy.bbclass</filename>:
602 <literallayout class='monospaced'> 605 <literallayout class='monospaced'>
603 DEPLOYDIR = "${WORKDIR}/deploy-${PN}" 606 DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
604 SSTATETASKS += "do_deploy" 607 SSTATETASKS += "do_deploy"
@@ -610,8 +613,9 @@
610 sstate_setscene(d) 613 sstate_setscene(d)
611 } 614 }
612 addtask do_deploy_setscene 615 addtask do_deploy_setscene
616 do_deploy[dirs] = "${DEPLOYDIR} ${B}"
613 </literallayout> 617 </literallayout>
614 In the example, we add some extra flags to the task, a name field ("deploy"), an 618 In this 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 619 input directory where the task sends data, and the output
616 directory where the data from the task should eventually be copied. 620 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 621 We also add a <filename>_setscene</filename> variant of the task and add the task
@@ -886,7 +890,7 @@
886 890
887 <para> 891 <para>
888 <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)#Weston'>Wayland</ulink> 892 <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)#Weston'>Wayland</ulink>
889 is a computer display server protocol that when implemented 893 is a computer display server protocol that
890 provides a method for compositing window managers to communicate 894 provides a method for compositing window managers to communicate
891 directly with applications and video hardware and expects them to 895 directly with applications and video hardware and expects them to
892 communicate with input hardware using other libraries. 896 communicate with input hardware using other libraries.
@@ -897,7 +901,7 @@
897 901
898 <para> 902 <para>
899 The Yocto Project provides the Wayland protocol libraries and the 903 The Yocto Project provides the Wayland protocol libraries and the
900 reference Weston compositor as part of it release. 904 reference Weston compositor as part of its release.
901 This section describes what you need to do to implement Wayland and 905 This section describes what you need to do to implement Wayland and
902 use the compositor when building an image for a supporting target. 906 use the compositor when building an image for a supporting target.
903 </para> 907 </para>
@@ -992,7 +996,7 @@
992 <para> 996 <para>
993 Alternatively, you can run Weston through the command-line 997 Alternatively, you can run Weston through the command-line
994 interpretor (CLI), which is better suited for development work. 998 interpretor (CLI), which is better suited for development work.
995 To run Weston under the CLI you need to do the following after 999 To run Weston under the CLI, you need to do the following after
996 your image is built: 1000 your image is built:
997 <orderedlist> 1001 <orderedlist>
998 <listitem><para>Run these commands to export 1002 <listitem><para>Run these commands to export
@@ -1181,7 +1185,7 @@
1181 </literallayout> 1185 </literallayout>
1182 As a convenience, you do not need to specify the complete license string 1186 As a convenience, you do not need to specify the complete license string
1183 in the whitelist for every package. 1187 in the whitelist for every package.
1184 you can use an abbreviated form, which consists 1188 You can use an abbreviated form, which consists
1185 of just the first portion or portions of the license string before 1189 of just the first portion or portions of the license string before
1186 the initial underscore character or characters. 1190 the initial underscore character or characters.
1187 A partial string will match 1191 A partial string will match
@@ -1203,10 +1207,10 @@
1203 License flag matching allows you to control what recipes the 1207 License flag matching allows you to control what recipes the
1204 OpenEmbedded build system includes in the build. 1208 OpenEmbedded build system includes in the build.
1205 Fundamentally, the build system attempts to match 1209 Fundamentally, the build system attempts to match
1206 <filename>LICENSE_FLAG</filename> strings found in 1210 <filename>LICENSE_FLAGS</filename> strings found in
1207 recipes against <filename>LICENSE_FLAGS_WHITELIST</filename> 1211 recipes against <filename>LICENSE_FLAGS_WHITELIST</filename>
1208 strings found in the whitelist. 1212 strings found in the whitelist.
1209 A match, causes the build system to include a recipe in the 1213 A match causes the build system to include a recipe in the
1210 build, while failure to find a match causes the build system to 1214 build, while failure to find a match causes the build system to
1211 exclude a recipe. 1215 exclude a recipe.
1212 </para> 1216 </para>
@@ -1267,7 +1271,7 @@
1267 1271
1268 <para> 1272 <para>
1269 This scheme works even if the 1273 This scheme works even if the
1270 <filename>LICENSE_FLAG</filename> string already 1274 <filename>LICENSE_FLAGS</filename> string already
1271 has <filename>_${PN}</filename> appended. 1275 has <filename>_${PN}</filename> appended.
1272 For example, the build system turns the license flag 1276 For example, the build system turns the license flag
1273 "commercial_1.2_foo" into "commercial_1.2_foo_foo" and would 1277 "commercial_1.2_foo" into "commercial_1.2_foo_foo" and would