summaryrefslogtreecommitdiffstats
path: root/documentation/overview-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/overview-manual')
-rw-r--r--documentation/overview-manual/overview-manual-concepts.xml135
1 files changed, 28 insertions, 107 deletions
diff --git a/documentation/overview-manual/overview-manual-concepts.xml b/documentation/overview-manual/overview-manual-concepts.xml
index f5337813df..af34b970aa 100644
--- a/documentation/overview-manual/overview-manual-concepts.xml
+++ b/documentation/overview-manual/overview-manual-concepts.xml
@@ -2495,24 +2495,39 @@
2495 second question assuming the build system can fetch the sstate 2495 second question assuming the build system can fetch the sstate
2496 objects from remote locations and install them if they are deemed 2496 objects from remote locations and install them if they are deemed
2497 to be valid. 2497 to be valid.
2498 <note> 2498 <note><title>Notes</title>
2499 The build system does not maintain 2499 <itemizedlist>
2500 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> 2500 <listitem><para>
2501 information as part of the shared state packages. 2501 The build system does not maintain
2502 Consequently, considerations exist that affect maintaining 2502 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
2503 shared state feeds. 2503 information as part of the shared state packages.
2504 For information on how the build system works with packages 2504 Consequently, considerations exist that affect
2505 and can track incrementing 2505 maintaining shared state feeds.
2506 <filename>PR</filename> information, see the 2506 For information on how the build system works with
2507 "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>" 2507 packages and can track incrementing
2508 section in the Yocto Project Development Tasks Manual. 2508 <filename>PR</filename> information, see the
2509 "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"
2510 section in the Yocto Project Development Tasks Manual.
2511 </para></listitem>
2512 <listitem><para>
2513 The code in the build system that supports incremental
2514 builds is not simple code.
2515 For techniques that help you work around issues related
2516 to shared state code, see the
2517 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-viewing-metadata-used-to-create-the-input-signature-of-a-shared-state-task'>Viewing Metadata Used to Create the Input Signature of a Shared State Task</ulink>"
2518 and
2519 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-invalidating-shared-state-to-force-a-task-to-run'>Invalidating Shared State to Force a Task to Run</ulink>"
2520 sections both in the Yocto Project Development Tasks
2521 Manual.
2522 </para></listitem>
2523 </itemizedlist>
2509 </note> 2524 </note>
2510 </para> 2525 </para>
2511 2526
2512 <para> 2527 <para>
2513 The rest of this section goes into detail about the overall 2528 The rest of this section goes into detail about the overall
2514 incremental build architecture, the checksums (signatures), shared 2529 incremental build architecture, the checksums (signatures), and
2515 state, and some tips and tricks. 2530 shared state.
2516 </para> 2531 </para>
2517 2532
2518 <section id='concepts-overall-architecture'> 2533 <section id='concepts-overall-architecture'>
@@ -2985,100 +3000,6 @@
2985 output from every task. 3000 output from every task.
2986 </para> 3001 </para>
2987 </section> 3002 </section>
2988
2989 <section id='concepts-tips-and-tricks'>
2990 <title>Tips and Tricks</title>
2991
2992 <para>
2993 The code in the build system that supports incremental builds
2994 is not simple code.
2995 This section presents some tips and tricks that help you work
2996 around issues related to shared state code.
2997 </para>
2998
2999 <section id='concepts-overview-debugging'>
3000 <title>Debugging</title>
3001
3002 <para>
3003 Seeing what metadata went into creating the input signature
3004 of a shared state (sstate) task can be a useful debugging
3005 aid.
3006 This information is available in signature information
3007 (<filename>siginfo</filename>) files in
3008 <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>.
3009 For information on how to view and interpret information in
3010 <filename>siginfo</filename> files, see the
3011 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</ulink>"
3012 section in the Yocto Project Development Tasks Manual.
3013 </para>
3014 </section>
3015
3016 <section id='concepts-invalidating-shared-state'>
3017 <title>Invalidating Shared State</title>
3018
3019 <para>
3020 The OpenEmbedded build system uses checksums and shared
3021 state cache to avoid unnecessarily rebuilding tasks.
3022 Collectively, this scheme is known as "shared state code."
3023 </para>
3024
3025 <para>
3026 As with all schemes, this one has some drawbacks.
3027 It is possible that you could make implicit changes to your
3028 code that the checksum calculations do not take into
3029 account.
3030 These implicit changes affect a task's output but do not
3031 trigger the shared state code into rebuilding a recipe.
3032 Consider an example during which a tool changes its output.
3033 Assume that the output of <filename>rpmdeps</filename>
3034 changes.
3035 The result of the change should be that all the
3036 <filename>package</filename> and
3037 <filename>package_write_rpm</filename> shared state cache
3038 items become invalid.
3039 However, because the change to the output is
3040 external to the code and therefore implicit,
3041 the associated shared state cache items do not become
3042 invalidated.
3043 In this case, the build process uses the cached items
3044 rather than running the task again.
3045 Obviously, these types of implicit changes can cause
3046 problems.
3047 </para>
3048
3049 <para>
3050 To avoid these problems during the build, you need to
3051 understand the effects of any changes you make.
3052 Realize that changes you make directly to a function
3053 are automatically factored into the checksum calculation.
3054 Thus, these explicit changes invalidate the associated
3055 area of shared state cache.
3056 However, you need to be aware of any implicit changes that
3057 are not obvious changes to the code and could affect
3058 the output of a given task.
3059 </para>
3060
3061 <para>
3062 When you identify an implicit change, you can easily
3063 take steps to invalidate the cache and force the tasks
3064 to run.
3065 The steps you can take are as simple as changing a
3066 function's comments in the source code.
3067 For example, to invalidate package shared state files,
3068 change the comment statements of
3069 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
3070 or the comments of one of the functions it calls.
3071 Even though the change is purely cosmetic, it causes the
3072 checksum to be recalculated and forces the build system to
3073 run the task again.
3074 <note>
3075 For an example of a commit that makes a cosmetic
3076 change to invalidate shared state, see this
3077 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>.
3078 </note>
3079 </para>
3080 </section>
3081 </section>
3082 </section> 3003 </section>
3083 3004
3084 <section id='automatically-added-runtime-dependencies'> 3005 <section id='automatically-added-runtime-dependencies'>