mirror of
https://git.yoctoproject.org/poky
synced 2026-01-29 21:08:42 +01:00
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>
This commit is contained in:
Scott Rifenbark
committed by
Richard Purdie
Richard Purdie
parent
dbdc897ca9
commit
3564ddf02c
@@ -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>
|
||||
|
||||
|
||||
@@ -2495,24 +2495,39 @@
|
||||
second question assuming the build system can fetch the sstate
|
||||
objects from remote locations and install them if they are deemed
|
||||
to be valid.
|
||||
<note>
|
||||
The build system does not maintain
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
|
||||
information as part of the shared state packages.
|
||||
Consequently, considerations exist that affect maintaining
|
||||
shared state feeds.
|
||||
For information on how the build system works with packages
|
||||
and can track incrementing
|
||||
<filename>PR</filename> information, see the
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"
|
||||
section in the Yocto Project Development Tasks Manual.
|
||||
<note><title>Notes</title>
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
The build system does not maintain
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
|
||||
information as part of the shared state packages.
|
||||
Consequently, considerations exist that affect
|
||||
maintaining shared state feeds.
|
||||
For information on how the build system works with
|
||||
packages and can track incrementing
|
||||
<filename>PR</filename> information, see the
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"
|
||||
section in the Yocto Project Development Tasks Manual.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
The code in the build system that supports incremental
|
||||
builds is not simple code.
|
||||
For techniques that help you work around issues related
|
||||
to shared state code, see the
|
||||
"<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>"
|
||||
and
|
||||
"<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>"
|
||||
sections both in the Yocto Project Development Tasks
|
||||
Manual.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</note>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The rest of this section goes into detail about the overall
|
||||
incremental build architecture, the checksums (signatures), shared
|
||||
state, and some tips and tricks.
|
||||
incremental build architecture, the checksums (signatures), and
|
||||
shared state.
|
||||
</para>
|
||||
|
||||
<section id='concepts-overall-architecture'>
|
||||
@@ -2985,100 +3000,6 @@
|
||||
output from every task.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='concepts-tips-and-tricks'>
|
||||
<title>Tips and Tricks</title>
|
||||
|
||||
<para>
|
||||
The code in the build system that supports incremental builds
|
||||
is not simple code.
|
||||
This section presents some tips and tricks that help you work
|
||||
around issues related to shared state code.
|
||||
</para>
|
||||
|
||||
<section id='concepts-overview-debugging'>
|
||||
<title>Debugging</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
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</ulink>"
|
||||
section in the Yocto Project Development Tasks Manual.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='concepts-invalidating-shared-state'>
|
||||
<title>Invalidating Shared State</title>
|
||||
|
||||
<para>
|
||||
The OpenEmbedded build system uses checksums and shared
|
||||
state 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>
|
||||
</section>
|
||||
|
||||
<section id='automatically-added-runtime-dependencies'>
|
||||
|
||||
Reference in New Issue
Block a user