summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-05-14 11:27:50 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-05-24 17:16:33 +0100
commitfd7f63eb5770e774fb6921845a9b1f9075ac3d35 (patch)
tree9ebad50f3af0fff7e6aa05810ac9a66b2dce8140 /documentation
parentad44dc9b7c17e9b291e0e162b7c211c6d7ecbaf4 (diff)
downloadpoky-fd7f63eb5770e774fb6921845a9b1f9075ac3d35.tar.gz
overview-manual: Updated "Shared State" section.
Added the line with "stamp-extra-info" flag to the example from the deploy.bbclass. This line was missing or it had been added since the original writing of this section. (From yocto-docs rev: 50f5482c2132235962d4ab48d0d7263628df1728) 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/overview-manual/overview-manual-concepts.xml70
1 files changed, 41 insertions, 29 deletions
diff --git a/documentation/overview-manual/overview-manual-concepts.xml b/documentation/overview-manual/overview-manual-concepts.xml
index 00a61b3a75..98c39a5976 100644
--- a/documentation/overview-manual/overview-manual-concepts.xml
+++ b/documentation/overview-manual/overview-manual-concepts.xml
@@ -2443,10 +2443,10 @@
2443 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink> 2443 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
2444 can determine that parts do not need to be rebuilt. 2444 can determine that parts do not need to be rebuilt.
2445 Fundamentally, building from scratch is attractive as it means all 2445 Fundamentally, building from scratch is attractive as it means all
2446 parts are built fresh and there is no possibility of stale data 2446 parts are built fresh and no possibility of stale data exists that
2447 causing problems. 2447 can cause problems.
2448 When developers hit problems, they typically default back to 2448 When developers hit problems, they typically default back to
2449 building from scratch so they know the state of things from the 2449 building from scratch so they have a know state from the
2450 start. 2450 start.
2451 </para> 2451 </para>
2452 2452
@@ -2482,10 +2482,9 @@
2482 </para> 2482 </para>
2483 2483
2484 <para> 2484 <para>
2485 For the first question, the 2485 For the first question, the build system detects changes in the
2486 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink> 2486 "inputs" to a given task by creating a checksum (or signature) of
2487 detects changes in the "inputs" to a given task by creating a 2487 the task's inputs.
2488 checksum (or signature) of the task's inputs.
2489 If the checksum changes, the system assumes the inputs have changed 2488 If the checksum changes, the system assumes the inputs have changed
2490 and the task needs to be rerun. 2489 and the task needs to be rerun.
2491 For the second question, the shared state (sstate) code tracks 2490 For the second question, the shared state (sstate) code tracks
@@ -2497,13 +2496,13 @@
2497 objects from remote locations and install them if they are deemed 2496 objects from remote locations and install them if they are deemed
2498 to be valid. 2497 to be valid.
2499 <note> 2498 <note>
2500 The OpenEmbedded build system does not maintain 2499 The build system does not maintain
2501 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> 2500 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
2502 information as part of the shared state packages. 2501 information as part of the shared state packages.
2503 Consequently, considerations exist that affect maintaining 2502 Consequently, considerations exist that affect maintaining
2504 shared state feeds. 2503 shared state feeds.
2505 For information on how the OpenEmbedded build system 2504 For information on how the build system works with packages
2506 works with packages and can track incrementing 2505 and can track incrementing
2507 <filename>PR</filename> information, see the 2506 <filename>PR</filename> information, see the
2508 "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>" 2507 "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"
2509 section in the Yocto Project Development Tasks Manual. 2508 section in the Yocto Project Development Tasks Manual.
@@ -2649,8 +2648,8 @@
2649 inputs into a task. 2648 inputs into a task.
2650 Information based on direct inputs is referred to as the 2649 Information based on direct inputs is referred to as the
2651 "basehash" in the code. 2650 "basehash" in the code.
2652 However, there is still the question of a task's indirect 2651 However, the question of a task's indirect inputs still
2653 inputs - the things that were already built and present in the 2652 exits - items already built and present in the
2654 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. 2653 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
2655 The checksum (or signature) for a particular task needs to add 2654 The checksum (or signature) for a particular task needs to add
2656 the hashes of all the tasks on which the particular task 2655 the hashes of all the tasks on which the particular task
@@ -2667,8 +2666,8 @@
2667 Within the BitBake configuration file, you can give BitBake 2666 Within the BitBake configuration file, you can give BitBake
2668 some extra information to help it construct the basehash. 2667 some extra information to help it construct the basehash.
2669 The following statement effectively results in a list of 2668 The following statement effectively results in a list of
2670 global variable dependency excludes - variables never 2669 global variable dependency excludes (i.e. variables never
2671 included in any checksum: 2670 included in any checksum):
2672 <literallayout class='monospaced'> 2671 <literallayout class='monospaced'>
2673 BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \ 2672 BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \
2674 SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \ 2673 SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \
@@ -2693,7 +2692,7 @@
2693 This file defines the two basic signature generators 2692 This file defines the two basic signature generators
2694 <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OE-Core</ulink> 2693 <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OE-Core</ulink>
2695 uses: "OEBasic" and "OEBasicHash". 2694 uses: "OEBasic" and "OEBasicHash".
2696 By default, there is a dummy "noop" signature handler enabled 2695 By default, a dummy "noop" signature handler is enabled
2697 in BitBake. 2696 in BitBake.
2698 This means that behavior is unchanged from previous versions. 2697 This means that behavior is unchanged from previous versions.
2699 OE-Core uses the "OEBasicHash" signature handler by default 2698 OE-Core uses the "OEBasicHash" signature handler by default
@@ -2704,14 +2703,13 @@
2704 </literallayout> 2703 </literallayout>
2705 The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> 2704 The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename>
2706 is the same as the "OEBasic" version but adds the task hash to 2705 is the same as the "OEBasic" version but adds the task hash to
2707 the stamp files. 2706 the
2708 This results in any 2707 <link linkend='stamp-files-and-the-rerunning-of-tasks'>stamp files</link>.
2709 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> 2708 This results in any metadata change that changes the task hash,
2710 change that changes the task hash, automatically 2709 automatically causing the task to be run again.
2711 causing the task to be run again.
2712 This removes the need to bump 2710 This removes the need to bump
2713 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> 2711 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
2714 values, and changes to Metadata automatically ripple across 2712 values, and changes to metadata automatically ripple across
2715 the build. 2713 the build.
2716 </para> 2714 </para>
2717 2715
@@ -2747,7 +2745,7 @@
2747 <para> 2745 <para>
2748 Checksums and dependencies, as discussed in the previous 2746 Checksums and dependencies, as discussed in the previous
2749 section, solve half the problem of supporting a shared state. 2747 section, solve half the problem of supporting a shared state.
2750 The other part of the problem is being able to use checksum 2748 The other half of the problem is being able to use checksum
2751 information during the build and being able to reuse or rebuild 2749 information during the build and being able to reuse or rebuild
2752 specific components. 2750 specific components.
2753 </para> 2751 </para>
@@ -2760,8 +2758,9 @@
2760 The idea is that the build process does not care about the 2758 The idea is that the build process does not care about the
2761 source of a task's output. 2759 source of a task's output.
2762 Output could be freshly built or it could be downloaded and 2760 Output could be freshly built or it could be downloaded and
2763 unpacked from somewhere - the build process does not need to 2761 unpacked from somewhere.
2764 worry about its origin. 2762 In other words, the build process does not need to worry about
2763 its origin.
2765 </para> 2764 </para>
2766 2765
2767 <para> 2766 <para>
@@ -2779,8 +2778,8 @@
2779 <para> 2778 <para>
2780 The Yocto Project team has tried to keep the details of the 2779 The Yocto Project team has tried to keep the details of the
2781 implementation hidden in <filename>sstate</filename> class. 2780 implementation hidden in <filename>sstate</filename> class.
2782 From a user's perspective, adding shared state wrapping to a task 2781 From a user's perspective, adding shared state wrapping to a
2783 is as simple as this 2782 task is as simple as this
2784 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-deploy'><filename>do_deploy</filename></ulink> 2783 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-deploy'><filename>do_deploy</filename></ulink>
2785 example taken from the 2784 example taken from the
2786 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-deploy'><filename>deploy</filename></ulink> 2785 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-deploy'><filename>deploy</filename></ulink>
@@ -2796,6 +2795,7 @@
2796 } 2795 }
2797 addtask do_deploy_setscene 2796 addtask do_deploy_setscene
2798 do_deploy[dirs] = "${DEPLOYDIR} ${B}" 2797 do_deploy[dirs] = "${DEPLOYDIR} ${B}"
2798 do_deploy[stamp-extra-info] = "${MACHINE_ARCH}"
2799 </literallayout> 2799 </literallayout>
2800 The following list explains the previous example: 2800 The following list explains the previous example:
2801 <itemizedlist> 2801 <itemizedlist>
@@ -2825,7 +2825,7 @@
2825 If <filename>do_deploy</filename> is not already in 2825 If <filename>do_deploy</filename> is not already in
2826 the shared state cache or if its input checksum 2826 the shared state cache or if its input checksum
2827 (signature) has changed from when the output was 2827 (signature) has changed from when the output was
2828 cached, the task will be run to populate the shared 2828 cached, the task runs to populate the shared
2829 state cache, after which the contents of the shared 2829 state cache, after which the contents of the shared
2830 state cache is copied to 2830 state cache is copied to
2831 <filename>${DEPLOY_DIR_IMAGE}</filename>. 2831 <filename>${DEPLOY_DIR_IMAGE}</filename>.
@@ -2833,7 +2833,7 @@
2833 state cache and its signature indicates that the 2833 state cache and its signature indicates that the
2834 cached output is still valid (i.e. if no 2834 cached output is still valid (i.e. if no
2835 relevant task inputs have changed), then the 2835 relevant task inputs have changed), then the
2836 contents of the shared state cache will be copied 2836 contents of the shared state cache copies
2837 directly to 2837 directly to
2838 <filename>${DEPLOY_DIR_IMAGE}</filename> by the 2838 <filename>${DEPLOY_DIR_IMAGE}</filename> by the
2839 <filename>do_deploy_setscene</filename> task 2839 <filename>do_deploy_setscene</filename> task
@@ -2890,6 +2890,18 @@
2890 </note> 2890 </note>
2891 </para></listitem> 2891 </para></listitem>
2892 <listitem><para> 2892 <listitem><para>
2893 The <filename>do_deploy[stamp-extra-info] = "${MACHINE_ARCH}"</filename>
2894 line appends extra metadata to the
2895 <link linkend='stamp-files-and-the-rerunning-of-tasks'>stamp file</link>.
2896 In this case, the metadata makes the task specific
2897 to a machine's architecture.
2898 See
2899 "<ulink url='&YOCTO_DOCS_BB_URL;#ref-bitbake-tasklist'>The Task List</ulink>"
2900 section in the BitBake User Manual for more
2901 information on the <filename>stamp-extra-info</filename>
2902 flag.
2903 </para></listitem>
2904 <listitem><para>
2893 <filename>sstate-inputdirs</filename> and 2905 <filename>sstate-inputdirs</filename> and
2894 <filename>sstate-outputdirs</filename> can also be used 2906 <filename>sstate-outputdirs</filename> can also be used
2895 with multiple directories. 2907 with multiple directories.
@@ -2970,7 +2982,7 @@
2970 Since the sysroot is not used, it would never get extracted. 2982 Since the sysroot is not used, it would never get extracted.
2971 This is another reason why a task-based approach is preferred 2983 This is another reason why a task-based approach is preferred
2972 over a recipe-based approach, which would have to install the 2984 over a recipe-based approach, which would have to install the
2973 output from every task.n 2985 output from every task.
2974 </para> 2986 </para>
2975 </section> 2987 </section>
2976 2988