ref-manual: Edits to the task chapter.

Minor edits based on feedback from Paul Eggleton.

(From yocto-docs rev: 71bd6b3e0c8f7abcd753240fd8a503b62443ad74)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 59 insertions, 24 deletions

diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml
index 5bff93b1c5..a62b7ce9a6 100644
--- a/documentation/ref-manual/ref-tasks.xml
+++ b/documentation/ref-manual/ref-tasks.xml
@@ -88,8 +88,6 @@
             <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
             variable and the argument's prefix to determine the correct
             fetcher module.
-            Unpacked source files reside in the
-            <link linkend='var-S'><filename>S</filename></link> directory.
         </para>
     </section>
 
@@ -123,16 +121,6 @@
         </para>
     </section>
 
-    <section id='ref-tasks-package_index'>
-        <title><filename>do_package_index</filename></title>
-
-        <para>
-            Creates or updates the index in the
-            <link linkend='package-feeds-dev-environment'>Package Feeds</link>
-            area.
-        </para>
-    </section>
-
     <section id='ref-tasks-package_write_deb'>
         <title><filename>do_package_write_deb</filename></title>
 
@@ -249,10 +237,16 @@
         <title><filename>do_unpack</filename></title>
 
         <para>
-            Unpacks the source code into a working directory.
-            For more information on fetching and unpacking source files, see the
+            Unpacks the source code into a working directory pointed to
+            by
+            <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}</filename>.
+            The
+            <link linkend='var-S'><filename>S</filename></link> variable also
+            plays a role in where unpacked source files ultimately reside.
+            For more information on how source files are unpacked, see the
             "<link linkend='source-fetching-dev-environment'>Source Fetching</link>"
-            section.
+            section and the <filename>WORKDIR</filename> and
+            <filename>S</filename> variable descriptions.
         </para>
     </section>
 </section>
@@ -262,7 +256,7 @@
 
     <para>
         These tasks are typically manually triggered (e.g. by using the
-        <filename>bitbake -c</filename> command line option):
+        <filename>bitbake -c</filename> command-line option):
     </para>
 
     <section id='ref-tasks-checkuri'>
@@ -290,6 +284,16 @@
 
         <para>
             Removes all output files for a target.
+            When this task is run, the
+            <link linkend='shared-state-cache'>sstate</link>) cache
+            files are not deleted.
+            Consequently, if no changes have been made and the recipe is
+            rebuilt after cleaning, output files are simply restored from the
+            sstate cache.
+            If you want to remove the sstate cache files for the recipe,
+            you need to use the
+            <link linkend='ref-tasks-cleansstate'><filename>do_cleansstate</filename></link>
+            task instead (i.e. <filename>bitbake -c cleansstate &lt;recipe&gt;</filename>).
         </para>
     </section>
 
@@ -313,14 +317,6 @@
         </para>
     </section>
 
-    <section id='ref-tasks-fetchall'>
-        <title><filename>do_fetchall</filename></title>
-
-        <para>
-            Fetches all remote sources required to build a target.
-        </para>
-    </section>
-
     <section id='ref-tasks-devshell'>
         <title><filename>do_devshell</filename></title>
 
@@ -334,6 +330,14 @@
         </para>
     </section>
 
+    <section id='ref-tasks-fetchall'>
+        <title><filename>do_fetchall</filename></title>
+
+        <para>
+            Fetches all remote sources required to build a target.
+        </para>
+    </section>
+
     <section id='ref-tasks-listtasks'>
         <title><filename>do_listtasks</filename></title>
 
@@ -341,6 +345,25 @@
             Lists all defined tasks for a target.
         </para>
     </section>
+
+    <section id='ref-tasks-package_index'>
+        <title><filename>do_package_index</filename></title>
+
+        <para>
+            Creates or updates the index in the
+            <link linkend='package-feeds-dev-environment'>Package Feeds</link>
+            area.
+            <note>
+                This task is not triggered with the
+                <filename>bitbake -c</filename> command-line option as
+                are the other tasks in this section.
+                Because this task is specifically for the
+                <filename>package-index</filename> recipe,
+                you run it using
+                <filename>bitbake package-index</filename>.
+            </note>
+        </para>
+    </section>
 </section>
 
 <section id='image-related-tasks'>
@@ -390,6 +413,9 @@
 
         <para>
             Boots an image and performs runtime tests within the image.
+            For information on automatically testing images, see the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
+            section in the Yocto Project Development Manual.
         </para>
     </section>
 
@@ -399,6 +425,15 @@
         <para>
             Boots an image and performs runtime tests within the image
             immediately after it has been built.
+            This task is enabled when you set
+            <link linkend='var-TEST_IMAGE'><filename>TEST_IMAGE</filename></link>
+            equal to "1".
+        </para>
+
+        <para>
+            For information on automatically testing images, see the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
+            section in the Yocto Project Development Manual.
         </para>
     </section>