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:
parent
b271f1196d
commit
0d9874d9a3
|
@ -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>
|
||||||
|
|
Loading…
Reference in New Issue