Bug 10345

Hello,

bitbake -C isn't mentioned at all in the reference manual and might be hard to
discover. Here are some suggested additions to '2.3.6 Running Specific Tasks',
which also clarify that '-c' respects dependencies and explain what it means
when a task is "tainted after a forced run":

Replace the "if you wish to rerun a task..." paragraph and the paragraphs that
follow it with the following:

  The '-c' flag respects task dependencies, meaning all other tasks (including
  from other recipes) that the specified task depends on will be run before the
  task. Even when manually specifying a task to run with '-c', BitBake will
  only run the task if it considers it "out of date". See
  [3.5.7. Stamp Files and the Rerunning of Tasks] for how BitBake determines
  whether a task is "out of date".
  
  If you want to force an up-to-date task to be rerun, e.g. because you made
  manual modifications to the recipe's [WORKDIR] that you want to try out, then
  you can add the '-f' flag.
  
  Note {
  The reason -f is never required when running the do_devshell task
  is that the [[nostamp]](http://www.yoctoproject.org/docs/2.2/bitbake-user-manual/bitbake-user-manual.html#variable-flags)
  variable flag set on it.
  }

  The following example shows one way in which the -f flag can be used:

  <same-as-before>
      $ bitbake matchbox-desktop
               .
               .
        make some changes to the source code in the work directory
               .
               .
     $ bitbake matchbox-desktop -c compile -f
     $ bitbake matchbox-desktop

  This sequence first builds and then recompiles matchbox-desktop. The last
  command reruns all tasks (basically the packaging tasks) after the compile.
  BitBake recognizes that the do_compile task was rerun and therefore
  understands that the other tasks also need to be run again.
  </same-as-before>

  Another, shorter way to rerun a task and all [normal recipe build task] that
  depend on it is to use the -C flag (note that the C is capital). This will
  invalidate the given task and then run the [do_build] task (the default task if
  no task is given) and the tasks it depends on. The final two commands in the
  above example can be replaced with the following single command:

     $ bitbake matchbox-desktop -C compile

  Internally, the -f and -C flags work by tainting (modifying) the input
  checksum of the specified task. This 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:

    WARNING: /home/ulf/poky/meta/recipes-sato/matchbox-desktop/matchbox-desktop_2.1.bb.do_compile is tainted from a forced run

  This is meant to warn you 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:

    $ bitbake matchbox-desktop -c clean
    $ bitbake matchbox-desktop
  }

  <same-as-before>
  You can view a list of tasks in a given package by running the do_listtasks task as follows:

     $ bitbake matchbox-desktop -c listtasks

  The results appear as output to the console and are also in the file ${WORKDIR}/temp/log.do_listtasks.  
  </same-as-before>


Cheers,
Ulf