summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/technical-details.xml
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-06-28 12:46:38 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-07-19 15:04:48 +0100
commit77031ba572f21f4acb8992f159b721004eaee188 (patch)
tree46d4c90a6750ee8177067c4a0788cf36b9c75d83 /documentation/ref-manual/technical-details.xml
parent57acc327242782e858b7c8eaeb474a05c29374c8 (diff)
downloadpoky-77031ba572f21f4acb8992f159b721004eaee188.tar.gz
ref-manual: Updated the flag descriptions for shared state details
Fixes [YOCTO 9823] I added more details to the explanations of how shared state is implemented. Included a bulleted list of the various statements of code to help explain flags and settings. (From yocto-docs rev: 518352f88c8dda16f2915a7bb9901ffd7686d739) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual/technical-details.xml')
-rw-r--r--documentation/ref-manual/technical-details.xml118
1 files changed, 118 insertions, 0 deletions
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index f6004908a9..8e0b9573bd 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -690,6 +690,123 @@
690 addtask do_deploy_setscene 690 addtask do_deploy_setscene
691 do_deploy[dirs] = "${DEPLOYDIR} ${B}" 691 do_deploy[dirs] = "${DEPLOYDIR} ${B}"
692 </literallayout> 692 </literallayout>
693 The following list explains the previous example:
694 <itemizedlist>
695 <listitem><para>
696 Adding "do_deploy" to <filename>SSTATETASKS</filename>
697 adds some required sstate-related processing, which is
698 implemented in the
699 <link linkend='ref-classes-sstate'><filename>sstate</filename></link>
700 class, to before and after the
701 <link linkend='ref-tasks-deploy'><filename>do_deploy</filename></link>
702 task.
703 </para></listitem>
704 <listitem><para>
705 The
706 <filename>do_deploy[sstate-inputsdirs] = "${DEPLOYDIR}"</filename>
707 declares that <filename>do_deploy</filename> places its
708 output in <filename>${DEPLOYDIR}</filename> when run
709 normally (i.e. when not using the sstate cache).
710 This output becomes the input to the shared state cache.
711 </para></listitem>
712 <listitem><para>
713 The
714 <filename>do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"</filename>
715 line causes the contents of the shared state cache to be
716 copied to <filename>${DEPLOY_DIR_IMAGE}</filename>.
717 <note>
718 If <filename>do_deploy</filename> is not already in
719 the shared state cache or if its input checksum
720 (signature) has changed from when the output was
721 cached, the task will be run to populate the shared
722 state cache, after which the contents of the shared
723 state cache is copied to
724 <filename>${DEPLOY_DIR_IMAGE}</filename>.
725 If <filename>do_deploy</filename> is in the shared
726 state cache and its signature indicates that the
727 cached output is still valid (i.e. if no
728 relevant task inputs have changed), then the contents
729 of the shared state cache will be copied directly to
730 <filename>${DEPLOY_DIR_IMAGE}</filename> by the
731 <filename>do_deploy_setscene</filename> task instead,
732 skipping the <filename>do_deploy</filename> task.
733 </note>
734 </para></listitem>
735 <listitem><para>
736 The following task definition is glue logic needed to make
737 the previous settings effective:
738 <literallayout class='monospaced'>
739 python do_deploy_setscene () {
740 sstate_setscene(d)
741 }
742 addtask do_deploy_setscene
743 </literallayout>
744 <filename>sstate_setscene()</filename> takes the flags
745 above as input and accelerates the
746 <filename>do_deploy</filename> task through the
747 shared state cache if possible.
748 If the task was accelerated,
749 <filename>sstate_setscene()</filename> returns True.
750 Otherwise, it returns False, and the normal
751 <filename>do_deploy</filename> task runs.
752 For more information, see the
753 "<ulink url='&YOCTO_DOCS_BB_URL;#setscene'>setscene</ulink>"
754 section in the BitBake User Manual.
755 </para></listitem>
756 <listitem><para>
757 The
758 <filename>do_deploy[dirs] = "${DEPLOYDIR} ${B}"</filename>
759 line creates <filename>${DEPLOYDIR}</filename> and
760 <filename>${B}</filename> before the
761 <filename>do_deploy</filename> task runs.
762 For more information, see the
763 "<ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'>Variable Flags</ulink>"
764 section in the BitBake User Manual.
765 <note>
766 In cases where
767 <filename>sstate-inputdirs</filename> and
768 <filename>sstate-outputdirs</filename> would be the
769 same, you can use
770 <filename>sstate-plaindirs</filename>.
771 For example, to preserve the
772 <filename>${PKGD}</filename> and
773 <filename>${PKGDEST}</filename> output from the
774 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
775 task, use the following:
776 <literallayout class='monospaced'>
777 do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
778 </literallayout>
779 </note>
780 </para></listitem>
781 <listitem><para>
782 <filename>sstate-inputdirs</filename> and
783 <filename>sstate-outputdirs</filename> can also be used
784 with multiple directories.
785 For example, the following declares
786 <filename>PKGDESTWORK</filename> and
787 <filename>SHLIBWORK</filename> as shared state
788 input directories, which populates the shared state
789 cache, and <filename>PKGDATA_DIR</filename> and
790 <filename>SHLIBSDIR</filename> as the corresponding
791 shared state output directories:
792 <literallayout class='monospaced'>
793 do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
794 do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
795 </literallayout>
796 </para></listitem>
797 <listitem><para>
798 These methods also include the ability to take a lockfile
799 when manipulating shared state directory structures,
800 for cases where file additions or removals are sensitive:
801 <literallayout class='monospaced'>
802 do_package[sstate-lockfile] = "${PACKAGELOCK}"
803 </literallayout>
804 </para></listitem>
805 </itemizedlist>
806 </para>
807
808<!--
809 <para>
693 In this example, we add some extra flags to the task, a name field ("deploy"), an 810 In this example, we add some extra flags to the task, a name field ("deploy"), an
694 input directory where the task sends data, and the output 811 input directory where the task sends data, and the output
695 directory where the data from the task should eventually be copied. 812 directory where the data from the task should eventually be copied.
@@ -713,6 +830,7 @@
713 shared state directory structures since some cases are sensitive to file 830 shared state directory structures since some cases are sensitive to file
714 additions or removals. 831 additions or removals.
715 </para> 832 </para>
833-->
716 834
717 <para> 835 <para>
718 Behind the scenes, the shared state code works by looking in 836 Behind the scenes, the shared state code works by looking in