diff options
-rw-r--r-- | documentation/ref-manual/technical-details.xml | 72 |
1 files changed, 45 insertions, 27 deletions
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml index be9c38709a..f4f432f928 100644 --- a/documentation/ref-manual/technical-details.xml +++ b/documentation/ref-manual/technical-details.xml | |||
@@ -730,43 +730,61 @@ | |||
730 | <title>Invalidating Shared State</title> | 730 | <title>Invalidating Shared State</title> |
731 | 731 | ||
732 | <para> | 732 | <para> |
733 | The shared state code uses checksums and shared state | 733 | The OpenEmbedded build system uses checksums and shared state |
734 | cache to avoid unnecessarily rebuilding tasks. | 734 | cache to avoid unnecessarily rebuilding tasks. |
735 | Collectively, this scheme is known as "shared state code." | ||
736 | </para> | ||
737 | |||
738 | <para> | ||
735 | As with all schemes, this one has some drawbacks. | 739 | As with all schemes, this one has some drawbacks. |
736 | It is possible that you could make implicit changes that are not factored | 740 | It is possible that you could make implicit changes to your |
737 | into the checksum calculation, but do affect a task's output. | 741 | code that the checksum calculations do not take into |
738 | A good example is perhaps when a tool changes its output. | 742 | account (i.e. implicit changes). |
739 | Assume that the output of <filename>rpmdeps</filename> needed to change. | 743 | These implicit changes affect a task's output but do not trigger |
744 | the shared state code into rebuilding a recipe. | ||
745 | Consider an example during which a tool changes its output. | ||
746 | Assume that the output of <filename>rpmdeps</filename> changes. | ||
740 | The result of the change should be that all the | 747 | The result of the change should be that all the |
741 | <filename>package</filename>, <filename>package_write_rpm</filename>, | 748 | <filename>package</filename> and |
742 | and <filename>package_deploy-rpm</filename> shared state cache | 749 | <filename>package_write_rpm</filename> shared state cache |
743 | items would become invalid. | 750 | items become invalid. |
744 | But, because this is a change that is external to the code and therefore implicit, | 751 | However, because the change to the output is |
745 | the associated shared state cache items do not become invalidated. | 752 | external to the code and therefore implicit, |
746 | In this case, the build process uses the cached items rather than running the | 753 | the associated shared state cache items do not become |
747 | task again. | 754 | invalidated. |
755 | In this case, the build process uses the cached items rather | ||
756 | than running the task again. | ||
748 | Obviously, these types of implicit changes can cause problems. | 757 | Obviously, these types of implicit changes can cause problems. |
749 | </para> | 758 | </para> |
750 | 759 | ||
751 | <para> | 760 | <para> |
752 | To avoid these problems during the build, you need to understand the effects of any | 761 | To avoid these problems during the build, you need to |
753 | change you make. | 762 | understand the effects of any changes you make. |
754 | Note that any changes you make directly to a function automatically are factored into | 763 | Realize that changes you make directly to a function |
755 | the checksum calculation and thus, will invalidate the associated area of sstate cache. | 764 | are automatically factored into the checksum calculation. |
756 | You need to be aware of any implicit changes that are not obvious changes to the | 765 | Thus, these explicit changes invalidate the associated area of |
757 | code and could affect the output of a given task. | 766 | sstate cache. |
758 | Once you are aware of such changes, you can take steps to invalidate the cache | 767 | However, you need to be aware of any implicit changes that |
759 | and force the tasks to run. | 768 | are not obvious changes to the code and could affect the output |
760 | The steps to take are as simple as changing function's comments in the source code. | 769 | of a given task. |
761 | For example, to invalidate package shared state files, change the comment statements | 770 | </para> |
762 | of <filename>do_package</filename> or the comments of one of the functions it calls. | 771 | |
763 | The change is purely cosmetic, but it causes the checksum to be recalculated and | 772 | <para> |
764 | forces the task to be run again. | 773 | When you identify an implicit change, you can easily take steps |
774 | to invalidate the cache and force the tasks to run. | ||
775 | The steps you can take are as simple as changing a function's | ||
776 | comments in the source code. | ||
777 | For example, to invalidate package shared state files, change | ||
778 | the comment statements of <filename>do_package</filename> or | ||
779 | the comments of one of the functions it calls. | ||
780 | Even though the change is purely cosmetic, it causes the | ||
781 | checksum to be recalculated and forces the OpenEmbedded build | ||
782 | system to run the task again. | ||
765 | </para> | 783 | </para> |
766 | 784 | ||
767 | <note> | 785 | <note> |
768 | For an example of a commit that makes a cosmetic change to invalidate | 786 | For an example of a commit that makes a cosmetic change to |
769 | a shared state, see this | 787 | invalidate shared state, see this |
770 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>. | 788 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>. |
771 | </note> | 789 | </note> |
772 | </section> | 790 | </section> |