From c2c052e34a669db13586647ec6dea7324e8901c4 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 3 Oct 2016 08:24:54 -0700 Subject: [PATCH] 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 Signed-off-by: Richard Purdie --- documentation/ref-manual/usingpoky.xml | 78 ++++++++++++++++++++++++-- 1 file changed, 73 insertions(+), 5 deletions(-) diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml index dcca7b2584..36525c47b0 100644 --- a/documentation/ref-manual/usingpoky.xml +++ b/documentation/ref-manual/usingpoky.xml @@ -606,15 +606,39 @@ - If you wish to rerun a task, use the -f force - option. - For example, the following sequence forces recompilation after - changing files in the work directory. + The -c 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 + -c, BitBake will only run the task if it + considers it "out of date". + See the + "Stamp Files and the Rerunning of Tasks" + section 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 use the + -f option. + + The reason -f is never required when + running the + do_devshell + task is because the + [nostamp] + variable flag is already set for the task. + + The following example shows one way you can use the + -f option: $ bitbake matchbox-desktop . . - make some changes to the source code in the work directory + make some changes to the source code in the work directory . . $ bitbake matchbox-desktop -c compile -f @@ -632,6 +656,50 @@ also need to be run again. + + Another, shorter way to rerun a task and all + normal recipe build tasks + that depend on it is to use the -C + option. + + This option is upper-cased and is separate from the + -c option, which is lower-cased. + + Using this option invalidates the given task and then runs the + do_build + 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: + + $ bitbake matchbox-desktop -C compile + + Internally, the -f and + -C 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. + + 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 + + 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: + + $ bitbake matchbox-desktop -c clean + $ bitbake matchbox-desktop + + + + You can view a list of tasks in a given package by running the do_listtasks task as follows: