[oe-commits] [bitbake] 02/05: bitbake-user-manual: Fleshed out the "addtask" documentation
git at git.openembedded.org
git at git.openembedded.org
Thu Oct 13 22:31:21 UTC 2016
rpurdie pushed a commit to branch 1.32
in repository bitbake.
commit c3373399c5d565de033c40a39e6f6f9399bb782e
Author: Scott Rifenbark <srifenbark at gmail.com>
AuthorDate: Mon Oct 10 12:39:59 2016 -0700
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 <srifenbark at gmail.com>
---
.../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 40f4829..e1b2f2d 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 @@
<title>Tasks</title>
<para>
- 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 (<filename>.bb</filename>
- or <filename>.inc</filename>) and class
- (<filename>.bbclass</filename>) files.
- By convention, task names begin with the string "do_".
- </para>
-
- <para>
- Here is an example of a task that prints out the date:
- <literallayout class='monospaced'>
- python do_printdate () {
- import time
- print time.strftime('%Y%m%d', time.gmtime())
- }
- addtask printdate after do_fetch before do_build
- </literallayout>
+ 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 <filename>.bb</filename> files and files
+ included or inherited from <filename>.bb</filename>
+ files).
+ By convention, tasks have names that start with "do_".
</para>
<section id='promoting-a-function-to-a-task'>
<title>Promoting a Function to a Task</title>
<para>
- Any function can be promoted to a task by applying the
+ Tasks are either
+ <link linkend='shell-functions'>shell functions</link> or
+ <link linkend='bitbake-style-python-functions'>BitBake-style Python functions</link>
+ that have been promoted to tasks by using the
<filename>addtask</filename> command.
- The <filename>addtask</filename> command also describes
- inter-task dependencies.
- Here is the function from the previous section but with the
- <filename>addtask</filename> command promoting it to a task
- and defining some dependencies:
+ The <filename>addtask</filename> 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:
<literallayout class='monospaced'>
python do_printdate () {
import time
@@ -1569,15 +1561,81 @@
}
addtask printdate after do_fetch before do_build
</literallayout>
- In the example, the function is defined and then promoted
- as a task.
- The <filename>do_printdate</filename> task becomes a dependency of
- the <filename>do_build</filename> task, which is the default
- task.
- And, the <filename>do_printdate</filename> task is dependent upon
- the <filename>do_fetch</filename> task.
- Execution of the <filename>do_build</filename> task results
- in the <filename>do_printdate</filename> task running first.
+ The first argument to <filename>addtask</filename>
+ 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_".
+ </para>
+
+ <para>
+ In the previous example, the
+ <filename>do_printdate</filename> task becomes a
+ dependency of the <filename>do_build</filename>
+ task, which is the default task (i.e. the task run by
+ the <filename>bitbake</filename> command unless
+ another task is specified explicitly).
+ Additionally, the <filename>do_printdate</filename>
+ task becomes dependent upon the
+ <filename>do_fetch</filename> task.
+ Running the <filename>do_build</filename> task
+ results in the <filename>do_printdate</filename>
+ task running first.
+ <note>
+ If you try out the previous example, you might see
+ the <filename>do_printdate</filename> task is only run
+ the first time you build the recipe with
+ the <filename>bitbake</filename> 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
+ <filename>[</filename><link linkend='variable-flags'><filename>nostamp</filename></link><filename>]</filename>
+ variable flag, as follows:
+ <literallayout class='monospaced'>
+ do_printdate[nostamp] = "1"
+ </literallayout>
+ You can also explicitly run the task and provide the
+ <filename>-f</filename> option as follows:
+ <literallayout class='monospaced'>
+ $ bitbake <replaceable>recipe</replaceable> -c printdate -f
+ </literallayout>
+ When manually selecting a task to run with the
+ <filename>bitbake</filename> <replaceable>recipe</replaceable> <filename>-c</filename> <replaceable>task</replaceable>
+ command, you can omit the "do_" prefix as part of the
+ task name.
+ </note>
+ </para>
+
+ <para>
+ You might wonder about the practical effects of using
+ <filename>addtask</filename> without specifying any
+ dependencies as is done in the following example:
+ <literallayout class='monospaced'>
+ addtask printdate
+ </literallayout>
+ 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
+ <filename>bitbake</filename> <replaceable>recipe</replaceable> <filename>-c printdate</filename>.
+ You can use the
+ <filename>do_listtasks</filename> task to list all tasks
+ defined in a recipe as shown in the following example:
+ <literallayout class='monospaced'>
+ $ bitbake <replaceable>recipe</replaceable> -c listtasks
+ </literallayout>
+ For more information on task dependencies, see the
+ "<link linkend='dependencies'>Dependencies</link>"
+ section.
+ </para>
+
+ <para>
+ See the
+ "<link linkend='variable-flags'>Variable Flags</link>"
+ section for information on variable flags you can use with
+ tasks.
</para>
</section>
--
To stop receiving notification emails like this one, please contact
the administrator of this repository.
More information about the Openembedded-commits
mailing list