summaryrefslogtreecommitdiffstats
path: root/bitbake/doc
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2014-02-05 16:31:46 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-03-09 18:59:01 -0700
commitae96cbb4c42fb047f1cd46d89110fe285a9c7dc6 (patch)
tree032f290530152d2a22ae9f7f9b77db084352cc68 /bitbake/doc
parentfaaca84d6e6d17d4a00ceec915672f3bd2f518b1 (diff)
downloadpoky-ae96cbb4c42fb047f1cd46d89110fe285a9c7dc6.tar.gz
bitbake: user-manual-metadata.xml: Rewrite of the "Tasks" section.
I cleaned up this section with some general improvements. I also broke this up into a couple sub-sections where it seemed to logically fall. Also, stole some metadata concept from the next section ("Running Tasks") that really should be lumped under "Tasks". (Bitbake rev: 9673acda2239807e31f4fcda1574b3e5e2d013a6) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'bitbake/doc')
-rw-r--r--bitbake/doc/user-manual/user-manual-metadata.xml155
1 files changed, 89 insertions, 66 deletions
diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml
index c2342a2236..002e866d6b 100644
--- a/bitbake/doc/user-manual/user-manual-metadata.xml
+++ b/bitbake/doc/user-manual/user-manual-metadata.xml
@@ -786,36 +786,104 @@
786 <section id='tasks'> 786 <section id='tasks'>
787 <title>Tasks</title> 787 <title>Tasks</title>
788 788
789 <note> 789 <para>
790 This is only supported in <filename>.bb</filename> 790 Tasks are BitBake execution units that originate as
791 and <filename>.bbclass</filename> files. 791 functions and make up the steps that BitBake needs to run
792 </note> 792 for given recipe.
793 Tasks are only supported in recipe (<filename>.bb</filename>)
794 and class (<filename>.bbclass</filename>) files.
795 By convention, tasks begin with the string "do_".
796 </para>
793 797
794 <para> 798 <para>
795 A shell or Python function executable through the 799 Here is an example of a task that prints out the date:
796 <filename>exec_func</filename> can be promoted to become a task.
797 Tasks are the execution unit Bitbake uses and each step that
798 needs to be run for a given <filename>.bb</filename> is known as
799 a task.
800 There is an <filename>addtask</filename> command to add new tasks
801 and promote functions which by convention must start with “do_”.
802 The <filename>addtask</filename> command is also used to describe
803 intertask dependencies.
804 <literallayout class='monospaced'> 800 <literallayout class='monospaced'>
805 python do_printdate () { 801 python do_printdate () {
806 import time print 802 import time print
807 time.strftime('%Y%m%d', time.gmtime()) 803 time.strftime('%Y%m%d', time.gmtime())
808 } 804 }
809 addtask printdate after do_fetch before do_build
810 </literallayout> 805 </literallayout>
811 The above example defined a Python function, then adds
812 it as a task which is now a dependency of
813 <filename>do_build</filename>, the default task and states it
814 has to happen after <filename>do_fetch</filename>.
815 If anyone executes the <filename>do_build</filename>
816 task, that will result in <filename>do_printdate</filename>
817 being run first.
818 </para> 806 </para>
807
808 <section id='promoting-a-function-to-a-task'>
809 <title>Promoting a Function to a Task</title>
810
811 <para>
812 Any function can be promoted to a task by applying the
813 <filename>addtask</filename> command.
814 The <filename>addtask</filename> command also describes
815 inter-task dependencies.
816 Here is the function from the previous section but with the
817 <filename>addtask</filename> command promoting it to a task
818 and defining some dependencies:
819 <literallayout class='monospaced'>
820 python do_printdate () {
821 import time print
822 time.strftime('%Y%m%d', time.gmtime())
823 }
824 addtask printdate after do_fetch before do_build
825 </literallayout>
826 In the example, the function is defined and then promoted
827 as a task.
828 The <filename>do_printdate</filename> task becomes a dependency of
829 the <filename>do_build</filename> task, which is the default
830 task.
831 And, the <filename>do_printdate</filename> task is dependent upon
832 the <filename>do_fetch</filename> task.
833 Execution of the <filename>do_build</filename> task results
834 in the <filename>do_printdate</filename> task running first.
835 </para>
836 </section>
837
838 <section id='passing-information-into-the-build-task-environment'>
839 <title>Passing Information Into the Build Task Environment</title>
840
841 <para>
842 When running a task, BitBake tightly controls the execution
843 environment of the build tasks to make
844 sure unwanted contamination from the build machine cannot
845 influence the build.
846 Consequently, if you do want something to get passed into the
847 build task environment, you must take these two steps:
848 <orderedlist>
849 <listitem><para>
850 Tell BitBake to load what you want from the environment
851 into the datastore.
852 You can do so through the
853 <link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link>
854 variable.
855 For example, assume you want to prevent the build system from
856 accessing your <filename>$HOME/.ccache</filename>
857 directory.
858 The following command tells BitBake to load
859 <filename>CCACHE_DIR</filename> from the environment into
860 the datastore:
861 <literallayout class='monospaced'>
862 export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
863 </literallayout></para></listitem>
864 <listitem><para>
865 Tell BitBake to export what you have loaded into the
866 datastore to the task environment of every running task.
867 Loading something from the environment into the datastore
868 (previous step) only makes it available in the datastore.
869 To export it to the task environment of every running task,
870 use a command similar to the following in your local configuration
871 file <filename>local.conf</filename> or your
872 distribution configuration file:
873 <literallayout class='monospaced'>
874 export CCACHE_DIR
875 </literallayout>
876 <note>
877 A side effect of the previous steps is that BitBake
878 records the variable as a dependency of the build process
879 in things like the setscene checksums.
880 If doing so results in unnecessary rebuilds of tasks, you can
881 whitelist the variable so that the setscene code
882 ignores the dependency when it creates checksums.
883 </note></para></listitem>
884 </orderedlist>
885 </para>
886 </section>
819 </section> 887 </section>
820 888
821 <section id='running-a-task'> 889 <section id='running-a-task'>
@@ -845,51 +913,6 @@
845 <para> 913 <para>
846 Once all the tasks have been completed BitBake exits. 914 Once all the tasks have been completed BitBake exits.
847 </para> 915 </para>
848
849 <para>
850 When running a task, BitBake tightly controls the execution
851 environment of the build tasks to make
852 sure unwanted contamination from the build machine cannot
853 influence the build.
854 Consequently, if you do want something to get passed into the
855 build task's environment, you must take a few steps:
856 <orderedlist>
857 <listitem><para>
858 Tell BitBake to load what you want from the environment
859 into the data store.
860 You can do so through the
861 <filename>BB_ENV_EXTRAWHITE</filename> variable.
862 For example, assume you want to prevent the build system from
863 accessing your <filename>$HOME/.ccache</filename>
864 directory.
865 The following command tells BitBake to load
866 <filename>CCACHE_DIR</filename> from the environment into
867 the data store:
868 <literallayout class='monospaced'>
869 export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
870 </literallayout></para></listitem>
871 <listitem><para>
872 Tell BitBake to export what you have loaded into the
873 environment store to the task environment of
874 every running task.
875 Loading something from the environment into the data
876 store (previous step) only makes it available in the datastore.
877 To export it to the task environment of every running task,
878 use a command similar to the following in your
879 <filename>local.conf</filename> or distribution configuration file:
880 <literallayout class='monospaced'>
881 export CCACHE_DIR
882 </literallayout>
883 <note>
884 A side effect of the previous steps is that BitBake
885 records the variable as a dependency of the build process
886 in things like the shared state checksums.
887 If doing so results in unnecessary rebuilds of tasks, you can
888 whitelist the variable so that the shared state code
889 ignores the dependency when it creates checksums.
890 </note></para></listitem>
891 </orderedlist>
892 </para>
893 </section> 916 </section>
894 917
895 <section id='variable-flags'> 918 <section id='variable-flags'>