summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-05-14 13:20:12 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-05-24 17:16:34 +0100
commit3564ddf02c03b865a0e85c4222c2ae6f71b156d3 (patch)
tree461c5412223b263c3fe688b1d2de19ff4ffc4418 /documentation
parentdbdc897ca90d84be513077b8d97a1177c199a222 (diff)
downloadpoky-3564ddf02c03b865a0e85c4222c2ae6f71b156d3.tar.gz
overview-manual, dev-manual: Moved sstate debug tips sections
Two sections at the end of the shared state concepts section in the overview-manual are really task sections. I took those and created a couple new sections in the dev-manual to house those topics. (From yocto-docs rev: 86382e7873d796f44554c8e04d3bd8091d350f51) 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/dev-manual/dev-manual-common-tasks.xml92
-rw-r--r--documentation/overview-manual/overview-manual-concepts.xml135
2 files changed, 120 insertions, 107 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 7330247819..5f7b66e411 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -12344,6 +12344,98 @@ Some notes from Cal:
12344 </para> 12344 </para>
12345 </section> 12345 </section>
12346 12346
12347 <section id='dev-viewing-metadata-used-to-create-the-input-signature-of-a-shared-state-task'>
12348 <title>Viewing Metadata Used to Create the Input Signature of a Shared State Task</title>
12349
12350 <para>
12351 Seeing what metadata went into creating the input signature
12352 of a shared state (sstate) task can be a useful debugging
12353 aid.
12354 This information is available in signature information
12355 (<filename>siginfo</filename>) files in
12356 <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>.
12357 For information on how to view and interpret information in
12358 <filename>siginfo</filename> files, see the
12359 "<link linkend='dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</link>"
12360 section.
12361 </para>
12362
12363 <para>
12364 For conceptual information on shared state, see the
12365 "<ulink url='&YOCTO_DOCS_OM_URL;#shared-state'>Shared State</ulink>"
12366 section in the Yocto Project Overview and Concepts Manual.
12367 </para>
12368 </section>
12369
12370 <section id='dev-invalidating-shared-state-to-force-a-task-to-run'>
12371 <title>Invalidating Shared State to Force a Task to Run</title>
12372
12373 <para>
12374 The OpenEmbedded build system uses
12375 <ulink url='&YOCTO_DOCS_OM_URL;#overview-checksums'>checksums</ulink>
12376 and
12377 <ulink url='&YOCTO_DOCS_OM_URL;#shared-state'>shared state</ulink>
12378 cache to avoid unnecessarily rebuilding tasks.
12379 Collectively, this scheme is known as "shared state code."
12380 </para>
12381
12382 <para>
12383 As with all schemes, this one has some drawbacks.
12384 It is possible that you could make implicit changes to your
12385 code that the checksum calculations do not take into
12386 account.
12387 These implicit changes affect a task's output but do not
12388 trigger the shared state code into rebuilding a recipe.
12389 Consider an example during which a tool changes its output.
12390 Assume that the output of <filename>rpmdeps</filename>
12391 changes.
12392 The result of the change should be that all the
12393 <filename>package</filename> and
12394 <filename>package_write_rpm</filename> shared state cache
12395 items become invalid.
12396 However, because the change to the output is
12397 external to the code and therefore implicit,
12398 the associated shared state cache items do not become
12399 invalidated.
12400 In this case, the build process uses the cached items
12401 rather than running the task again.
12402 Obviously, these types of implicit changes can cause
12403 problems.
12404 </para>
12405
12406 <para>
12407 To avoid these problems during the build, you need to
12408 understand the effects of any changes you make.
12409 Realize that changes you make directly to a function
12410 are automatically factored into the checksum calculation.
12411 Thus, these explicit changes invalidate the associated
12412 area of shared state cache.
12413 However, you need to be aware of any implicit changes that
12414 are not obvious changes to the code and could affect
12415 the output of a given task.
12416 </para>
12417
12418 <para>
12419 When you identify an implicit change, you can easily
12420 take steps to invalidate the cache and force the tasks
12421 to run.
12422 The steps you can take are as simple as changing a
12423 function's comments in the source code.
12424 For example, to invalidate package shared state files,
12425 change the comment statements of
12426 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
12427 or the comments of one of the functions it calls.
12428 Even though the change is purely cosmetic, it causes the
12429 checksum to be recalculated and forces the build system to
12430 run the task again.
12431 <note>
12432 For an example of a commit that makes a cosmetic
12433 change to invalidate shared state, see this
12434 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>.
12435 </note>
12436 </para>
12437 </section>
12438
12347 <section id='dev-debugging-taskrunning'> 12439 <section id='dev-debugging-taskrunning'>
12348 <title>Running Specific Tasks</title> 12440 <title>Running Specific Tasks</title>
12349 12441
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'>