diff options
author | Scott Rifenbark <srifenbark@gmail.com> | 2018-05-14 13:20:12 -0700 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2018-05-24 17:16:34 +0100 |
commit | 3564ddf02c03b865a0e85c4222c2ae6f71b156d3 (patch) | |
tree | 461c5412223b263c3fe688b1d2de19ff4ffc4418 /documentation/overview-manual | |
parent | dbdc897ca90d84be513077b8d97a1177c199a222 (diff) | |
download | openembedded-core-contrib-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/overview-manual')
-rw-r--r-- | documentation/overview-manual/overview-manual-concepts.xml | 135 |
1 files changed, 28 insertions, 107 deletions
diff --git a/documentation/overview-manual/overview-manual-concepts.xml b/documentation/overview-manual/overview-manual-concepts.xml index f5337813df..af34b970aa 100644 --- a/documentation/overview-manual/overview-manual-concepts.xml +++ b/documentation/overview-manual/overview-manual-concepts.xml @@ -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'> |