[gnome-continuous-yocto/gnomeostree-3.28-rocko: 2958/8267] ref-manual: Added explanation of the -C option

[Emmanuele Bassi <ebassi src gnome org>]

commit c2c052e34a669db13586647ec6dea7324e8901c4
Author: Scott Rifenbark <srifenbark gmail com>
Date:   Mon Oct 3 08:24:54 2016 -0700

    ref-manual: Added explanation of the -C option
    
    Fixes [YOCTO #10345]
    
    There was no mention of the -C option in the "Running Specific
    Tasks" section.  I added information to cover this command-line
    option.
    
    (From yocto-docs rev: 7b05c5dd3816414c1d3ca898fbd41ce588425057)
    
    Signed-off-by: Scott Rifenbark <srifenbark gmail com>
    Signed-off-by: Richard Purdie <richard purdie linuxfoundation org>

 documentation/ref-manual/usingpoky.xml |   78 +++++++++++++++++++++++++++++--
 1 files changed, 73 insertions(+), 5 deletions(-)
---
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index dcca7b2..36525c4 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -606,15 +606,39 @@
         </para>
 
         <para>
-            If you wish to rerun a task, use the <filename>-f</filename> force
-            option.
-            For example, the following sequence forces recompilation after
-            changing files in the work directory.
+            The <filename>-c</filename> option respects task dependencies,
+            which means that all other tasks (including tasks from other
+            recipes) that the specified task depends on will be run before the
+            task.
+            Even when you manually specify a task to run with
+            <filename>-c</filename>, BitBake will only run the task if it
+            considers it "out of date".
+            See the
+            "<link linkend='stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of 
Tasks</link>"
+            section for how BitBake determines whether a task is "out of date".
+        </para>
+
+        <para>
+            If you want to force an up-to-date task to be rerun (e.g.
+            because you made manual modifications to the recipe's
+            <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
+            that you want to try out), then you can use the
+            <filename>-f</filename> option.
+            <note>
+                The reason <filename>-f</filename> is never required when
+                running the
+                <link linkend='ref-tasks-devshell'><filename>do_devshell</filename></link>
+                task is because the
+                <filename>[</filename><ulink 
url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>nostamp</filename></ulink><filename>]</filename>
+                variable flag is already set for the task.
+            </note>
+            The following example shows one way you can use the
+            <filename>-f</filename> option:
             <literallayout class='monospaced'>
      $ bitbake matchbox-desktop
                .
                .
-        <replaceable>make some changes to the source code in the work directory</replaceable>
+     make some changes to the source code in the work directory
                .
                .
      $ bitbake matchbox-desktop -c compile -f
@@ -633,6 +657,50 @@
         </para>
 
         <para>
+            Another, shorter way to rerun a task and all
+            <link linkend='normal-recipe-build-tasks'>normal recipe build tasks</link>
+            that depend on it is to use the <filename>-C</filename>
+            option.
+            <note>
+                This option is upper-cased and is separate from the
+                <filename>-c</filename> option, which is lower-cased.
+            </note>
+            Using this option invalidates the given task and then runs the
+            <link linkend='ref-tasks-build'><filename>do_build</filename></link>
+            task, which is the default task if no task is given, and the
+            tasks on which it depends.
+            You could replace the final two commands in the previous example
+            with the following single command:
+            <literallayout class='monospaced'>
+     $ bitbake matchbox-desktop -C compile
+            </literallayout>
+            Internally, the <filename>-f</filename> and
+            <filename>-C</filename> options work by tainting (modifying) the
+            input checksum of the specified task.
+            This tainting indirectly causes the task and its
+            dependent tasks to be rerun through the normal task dependency
+            mechanisms.
+            <note>
+                BitBake explicitly keeps track of which tasks have been
+                tainted in this fashion, and will print warnings such as the
+                following for builds involving such tasks:
+                <literallayout class='monospaced'>
+     WARNING: /home/ulf/poky/meta/recipes-sato/matchbox-desktop/matchbox-desktop_2.1.bb.do_compile is 
tainted from a forced run
+                </literallayout>
+                The purpose of the warning is to let you know that the work
+                directory and build output might not be in the clean state they
+                would be in for a "normal" build, depending on what actions
+                you took.
+                To get rid of such warnings, you can remove the work directory
+                and rebuild the recipe, as follows:
+                <literallayout class='monospaced'>
+     $ bitbake matchbox-desktop -c clean
+     $ bitbake matchbox-desktop
+                </literallayout>
+            </note>
+        </para>
+
+        <para>
             You can view a list of tasks in a given package by running the
             <filename>do_listtasks</filename> task as follows:
             <literallayout class='monospaced'>