mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-05-30 00:20:08 +00:00
Code Issues Projects Releases Wiki Activity

overview-manual, dev-manual: Moved sstate debug tips sections

Browse Source 
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>
This commit is contained in:
Scott Rifenbark
2018-05-14 13:20:12 -07:00
committed by Richard Purdie
parent dbdc897ca9
commit 3564ddf02c
2 changed files with 120 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/dev-manual/dev-manual-common-tasks.xml
+92
View File
@@ -12344,6 +12344,98 @@ Some notes from Cal:
</para>
</section>
<section id='dev-viewing-metadata-used-to-create-the-input-signature-of-a-shared-state-task'>
<title>Viewing Metadata Used to Create the Input Signature of a Shared State Task</title>
<para>
Seeing what metadata went into creating the input signature
of a shared state (sstate) task can be a useful debugging
aid.
This information is available in signature information
(<filename>siginfo</filename>) files in
<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>.
For information on how to view and interpret information in
<filename>siginfo</filename> files, see the
"<link linkend='dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</link>"
section.
</para>
<para>
For conceptual information on shared state, see the
"<ulink url='&YOCTO_DOCS_OM_URL;#shared-state'>Shared State</ulink>"
section in the Yocto Project Overview and Concepts Manual.
</para>
</section>
<section id='dev-invalidating-shared-state-to-force-a-task-to-run'>
<title>Invalidating Shared State to Force a Task to Run</title>
<para>
The OpenEmbedded build system uses
<ulink url='&YOCTO_DOCS_OM_URL;#overview-checksums'>checksums</ulink>
and
<ulink url='&YOCTO_DOCS_OM_URL;#shared-state'>shared state</ulink>
cache to avoid unnecessarily rebuilding tasks.
Collectively, this scheme is known as "shared state code."
</para>
<para>
As with all schemes, this one has some drawbacks.
It is possible that you could make implicit changes to your
code that the checksum calculations do not take into
account.
These implicit changes affect a task's output but do not
trigger the shared state code into rebuilding a recipe.
Consider an example during which a tool changes its output.
Assume that the output of <filename>rpmdeps</filename>
changes.
The result of the change should be that all the
<filename>package</filename> and
<filename>package_write_rpm</filename> shared state cache
items become invalid.
However, because the change to the output is
external to the code and therefore implicit,
the associated shared state cache items do not become
invalidated.
In this case, the build process uses the cached items
rather than running the task again.
Obviously, these types of implicit changes can cause
problems.
</para>
<para>
To avoid these problems during the build, you need to
understand the effects of any changes you make.
Realize that changes you make directly to a function
are automatically factored into the checksum calculation.
Thus, these explicit changes invalidate the associated
area of shared state cache.
However, you need to be aware of any implicit changes that
are not obvious changes to the code and could affect
the output of a given task.
</para>
<para>
When you identify an implicit change, you can easily
take steps to invalidate the cache and force the tasks
to run.
The steps you can take are as simple as changing a
function's comments in the source code.
For example, to invalidate package shared state files,
change the comment statements of
<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
or the comments of one of the functions it calls.
Even though the change is purely cosmetic, it causes the
checksum to be recalculated and forces the build system to
run the task again.
<note>
For an example of a commit that makes a cosmetic
change to invalidate shared state, see this
<ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>.
</note>
</para>
</section>
<section id='dev-debugging-taskrunning'>
<title>Running Specific Tasks</title>