diff options
author | Scott Rifenbark <srifenbark@gmail.com> | 2016-10-03 08:24:54 -0700 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2016-10-11 08:51:21 +0100 |
commit | c2c052e34a669db13586647ec6dea7324e8901c4 (patch) | |
tree | 0aa4c73f627a59d1356fe3433e278d6dc441cbe9 /documentation | |
parent | e2083c04c75602475e39f6654a4e1303b8f105e4 (diff) | |
download | openembedded-core-contrib-c2c052e34a669db13586647ec6dea7324e8901c4.tar.gz |
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>
Diffstat (limited to 'documentation')
-rw-r--r-- | 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 dcca7b2584..36525c47b0 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'> |