summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-common-tasks.xml
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/dev-manual/dev-manual-common-tasks.xml
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/dev-manual/dev-manual-common-tasks.xml')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml92
1 files changed, 92 insertions, 0 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