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 @@
Tasks - - This is only supported in .bb - and .bbclass files. - + + Tasks are BitBake execution units that originate as + functions and make up the steps that BitBake needs to run + for given recipe. + Tasks are only supported in recipe (.bb) + and class (.bbclass) files. + By convention, tasks begin with the string "do_". + - A shell or Python function executable through the - exec_func can be promoted to become a task. - Tasks are the execution unit Bitbake uses and each step that - needs to be run for a given .bb is known as - a task. - There is an addtask command to add new tasks - and promote functions which by convention must start with “do_”. - The addtask command is also used to describe - intertask dependencies. + Here is an example of a task that prints out the date: python do_printdate () { import time print time.strftime('%Y%m%d', time.gmtime()) } - addtask printdate after do_fetch before do_build - The above example defined a Python function, then adds - it as a task which is now a dependency of - do_build, the default task and states it - has to happen after do_fetch. - If anyone executes the do_build - task, that will result in do_printdate - being run first. + +
+ Promoting a Function to a Task + + + Any function can be promoted to a task by applying the + addtask command. + The addtask command also describes + inter-task dependencies. + Here is the function from the previous section but with the + addtask command promoting it to a task + and defining some dependencies: + + python do_printdate () { + import time print + time.strftime('%Y%m%d', time.gmtime()) + } + addtask printdate after do_fetch before do_build + + In the example, the function is defined and then promoted + as a task. + The do_printdate task becomes a dependency of + the do_build task, which is the default + task. + And, the do_printdate task is dependent upon + the do_fetch task. + Execution of the do_build task results + in the do_printdate task running first. + +
+ +
+ Passing Information Into the Build Task Environment + + + When running a task, BitBake tightly controls the execution + environment of the build tasks to make + sure unwanted contamination from the build machine cannot + influence the build. + Consequently, if you do want something to get passed into the + build task environment, you must take these two steps: + + + Tell BitBake to load what you want from the environment + into the datastore. + You can do so through the + BB_ENV_EXTRAWHITE + variable. + For example, assume you want to prevent the build system from + accessing your $HOME/.ccache + directory. + The following command tells BitBake to load + CCACHE_DIR from the environment into + the datastore: + + export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR" + + + Tell BitBake to export what you have loaded into the + datastore to the task environment of every running task. + Loading something from the environment into the datastore + (previous step) only makes it available in the datastore. + To export it to the task environment of every running task, + use a command similar to the following in your local configuration + file local.conf or your + distribution configuration file: + + export CCACHE_DIR + + + A side effect of the previous steps is that BitBake + records the variable as a dependency of the build process + in things like the setscene checksums. + If doing so results in unnecessary rebuilds of tasks, you can + whitelist the variable so that the setscene code + ignores the dependency when it creates checksums. + + + +
@@ -845,51 +913,6 @@ Once all the tasks have been completed BitBake exits. - - - When running a task, BitBake tightly controls the execution - environment of the build tasks to make - sure unwanted contamination from the build machine cannot - influence the build. - Consequently, if you do want something to get passed into the - build task's environment, you must take a few steps: - - - Tell BitBake to load what you want from the environment - into the data store. - You can do so through the - BB_ENV_EXTRAWHITE variable. - For example, assume you want to prevent the build system from - accessing your $HOME/.ccache - directory. - The following command tells BitBake to load - CCACHE_DIR from the environment into - the data store: - - export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR" - - - Tell BitBake to export what you have loaded into the - environment store to the task environment of - every running task. - Loading something from the environment into the data - store (previous step) only makes it available in the datastore. - To export it to the task environment of every running task, - use a command similar to the following in your - local.conf or distribution configuration file: - - export CCACHE_DIR - - - A side effect of the previous steps is that BitBake - records the variable as a dependency of the build process - in things like the shared state checksums. - If doing so results in unnecessary rebuilds of tasks, you can - whitelist the variable so that the shared state code - ignores the dependency when it creates checksums. - - -