summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/usingpoky.xml78
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 @@
606 </para> 606 </para>
607 607
608 <para> 608 <para>
609 If you wish to rerun a task, use the <filename>-f</filename> force 609 The <filename>-c</filename> option respects task dependencies,
610 option. 610 which means that all other tasks (including tasks from other
611 For example, the following sequence forces recompilation after 611 recipes) that the specified task depends on will be run before the
612 changing files in the work directory. 612 task.
613 Even when you manually specify a task to run with
614 <filename>-c</filename>, BitBake will only run the task if it
615 considers it "out of date".
616 See the
617 "<link linkend='stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</link>"
618 section for how BitBake determines whether a task is "out of date".
619 </para>
620
621 <para>
622 If you want to force an up-to-date task to be rerun (e.g.
623 because you made manual modifications to the recipe's
624 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
625 that you want to try out), then you can use the
626 <filename>-f</filename> option.
627 <note>
628 The reason <filename>-f</filename> is never required when
629 running the
630 <link linkend='ref-tasks-devshell'><filename>do_devshell</filename></link>
631 task is because the
632 <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>nostamp</filename></ulink><filename>]</filename>
633 variable flag is already set for the task.
634 </note>
635 The following example shows one way you can use the
636 <filename>-f</filename> option:
613 <literallayout class='monospaced'> 637 <literallayout class='monospaced'>
614 $ bitbake matchbox-desktop 638 $ bitbake matchbox-desktop
615 . 639 .
616 . 640 .
617 <replaceable>make some changes to the source code in the work directory</replaceable> 641 make some changes to the source code in the work directory
618 . 642 .
619 . 643 .
620 $ bitbake matchbox-desktop -c compile -f 644 $ bitbake matchbox-desktop -c compile -f
@@ -633,6 +657,50 @@
633 </para> 657 </para>
634 658
635 <para> 659 <para>
660 Another, shorter way to rerun a task and all
661 <link linkend='normal-recipe-build-tasks'>normal recipe build tasks</link>
662 that depend on it is to use the <filename>-C</filename>
663 option.
664 <note>
665 This option is upper-cased and is separate from the
666 <filename>-c</filename> option, which is lower-cased.
667 </note>
668 Using this option invalidates the given task and then runs the
669 <link linkend='ref-tasks-build'><filename>do_build</filename></link>
670 task, which is the default task if no task is given, and the
671 tasks on which it depends.
672 You could replace the final two commands in the previous example
673 with the following single command:
674 <literallayout class='monospaced'>
675 $ bitbake matchbox-desktop -C compile
676 </literallayout>
677 Internally, the <filename>-f</filename> and
678 <filename>-C</filename> options work by tainting (modifying) the
679 input checksum of the specified task.
680 This tainting indirectly causes the task and its
681 dependent tasks to be rerun through the normal task dependency
682 mechanisms.
683 <note>
684 BitBake explicitly keeps track of which tasks have been
685 tainted in this fashion, and will print warnings such as the
686 following for builds involving such tasks:
687 <literallayout class='monospaced'>
688 WARNING: /home/ulf/poky/meta/recipes-sato/matchbox-desktop/matchbox-desktop_2.1.bb.do_compile is tainted from a forced run
689 </literallayout>
690 The purpose of the warning is to let you know that the work
691 directory and build output might not be in the clean state they
692 would be in for a "normal" build, depending on what actions
693 you took.
694 To get rid of such warnings, you can remove the work directory
695 and rebuild the recipe, as follows:
696 <literallayout class='monospaced'>
697 $ bitbake matchbox-desktop -c clean
698 $ bitbake matchbox-desktop
699 </literallayout>
700 </note>
701 </para>
702
703 <para>
636 You can view a list of tasks in a given package by running the 704 You can view a list of tasks in a given package by running the
637 <filename>do_listtasks</filename> task as follows: 705 <filename>do_listtasks</filename> task as follows:
638 <literallayout class='monospaced'> 706 <literallayout class='monospaced'>