sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

ref-manual: re-wrote the "Invalidating Shared State" section 

Investigating this section for an apparent typo it was decided
that the term needed removed.  During the process I re-wrote
the section for clarity.

(From yocto-docs rev: 8ba011f9f3066bb821b8b371f20f1f9522960a2e)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark 2013-11-06 07:55:45 -08:00 committed by Richard Purdie
parent b271f1196d
commit 0d9874d9a3
1 changed files with 45 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
documentation/ref-manual/technical-details.xml
View File

@ -730,43 +730,61 @@
<title>Invalidating Shared State</title> <title>Invalidating Shared State</title>
<para> <para>
The shared state code uses checksums and shared state The OpenEmbedded build system uses checksums and shared state
cache to avoid unnecessarily rebuilding tasks. 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. As with all schemes, this one has some drawbacks.
It is possible that you could make implicit changes that are not factored It is possible that you could make implicit changes to your
into the checksum calculation, but do affect a task's output. code that the checksum calculations do not take into
A good example is perhaps when a tool changes its output. account (i.e. implicit changes).
Assume that the output of <filename>rpmdeps</filename> needed to change. 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 The result of the change should be that all the
<filename>package</filename>, <filename>package_write_rpm</filename>, <filename>package</filename> and
and <filename>package_deploy-rpm</filename> shared state cache <filename>package_write_rpm</filename> shared state cache
items would become invalid. items become invalid.
But, because this is a change that is external to the code and therefore implicit, However, because the change to the output is
the associated shared state cache items do not become invalidated. external to the code and therefore implicit,
In this case, the build process uses the cached items rather than running the the associated shared state cache items do not become
task again. 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. Obviously, these types of implicit changes can cause problems.
</para> </para>
<para> <para>
To avoid these problems during the build, you need to understand the effects of any To avoid these problems during the build, you need to
change you make. understand the effects of any changes you make.
Note that any changes you make directly to a function automatically are factored into Realize that changes you make directly to a function
the checksum calculation and thus, will invalidate the associated area of sstate cache. are automatically factored into the checksum calculation.
You need to be aware of any implicit changes that are not obvious changes to the Thus, these explicit changes invalidate the associated area of
code and could affect the output of a given task. sstate cache.
Once you are aware of such changes, you can take steps to invalidate the cache However, you need to be aware of any implicit changes that
and force the tasks to run. are not obvious changes to the code and could affect the output
The steps to take are as simple as changing function's comments in the source code. of a given task.
For example, to invalidate package shared state files, change the comment statements </para>
of <filename>do_package</filename> or the comments of one of the functions it calls.
The change is purely cosmetic, but it causes the checksum to be recalculated and <para>
forces the task to be run again. 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 <filename>do_package</filename> 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 OpenEmbedded build
system to run the task again.
</para> </para>
<note> <note>
For an example of a commit that makes a cosmetic change to invalidate For an example of a commit that makes a cosmetic change to
a shared state, see this invalidate shared state, see this
<ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>. <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>.
</note> </note>
</section> </section>