From c3373399c5d565de033c40a39e6f6f9399bb782e Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 10 Oct 2016 12:39:59 -0700 Subject: bitbake-user-manual: Fleshed out the "addtask" documentation Fixes [YOCTO #10401] The "addtask" documentation was rewritten to tighten up the introductory section and to flesh out the actual examples. Signed-off-by: Scott Rifenbark --- .../bitbake-user-manual-metadata.xml | 124 +++++++++++++++------ 1 file changed, 91 insertions(+), 33 deletions(-) diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml index 40f4829e6..e1b2f2d0b 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml +++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml @@ -1531,37 +1531,29 @@ Tasks - 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 - or .inc) and class - (.bbclass) files. - By convention, task names begin with the string "do_". - - - - 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 - + Tasks are BitBake execution units that make up the + steps that BitBake can run for a given recipe. + Tasks are only supported in recipes and classes + (i.e. in .bb files and files + included or inherited from .bb + files). + By convention, tasks have names that start with "do_".
Promoting a Function to a Task - Any function can be promoted to a task by applying the + Tasks are either + shell functions or + BitBake-style Python functions + that have been promoted to tasks by using 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: + The addtask command can also + optionally describe dependencies between the + task and other tasks. + Here is an example that shows how to define a task + and to declare some dependencies: python do_printdate () { import time @@ -1569,15 +1561,81 @@ } 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. + The first argument to addtask + is the name of the function to promote to + a task. + If the name does not start with "do_", "do_" is + implicitly added, which enforces the convention that + all task names start with "do_". + + + + In the previous example, the + do_printdate task becomes a + dependency of the do_build + task, which is the default task (i.e. the task run by + the bitbake command unless + another task is specified explicitly). + Additionally, the do_printdate + task becomes dependent upon the + do_fetch task. + Running the do_build task + results in the do_printdate + task running first. + + If you try out the previous example, you might see + the do_printdate task is only run + the first time you build the recipe with + the bitbake command. + This is because BitBake considers the task "up-to-date" + after that initial run. + If you want to force the task to always be rerun for + experimentation purposes, you can make BitBake always + consider the task "out-of-date" by using the + [nostamp] + variable flag, as follows: + + do_printdate[nostamp] = "1" + + You can also explicitly run the task and provide the + -f option as follows: + + $ bitbake recipe -c printdate -f + + When manually selecting a task to run with the + bitbake recipe -c task + command, you can omit the "do_" prefix as part of the + task name. + + + + + You might wonder about the practical effects of using + addtask without specifying any + dependencies as is done in the following example: + + addtask printdate + + In this example, assuming dependencies have not been + added through some other means, the only way to run + the task is by explicitly selecting it with the + bitbake recipe -c printdate. + You can use the + do_listtasks task to list all tasks + defined in a recipe as shown in the following example: + + $ bitbake recipe -c listtasks + + For more information on task dependencies, see the + "Dependencies" + section. + + + + See the + "Variable Flags" + section for information on variable flags you can use with + tasks.
-- cgit 1.2.3-korg