sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

bitbake: 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.

(Bitbake rev: c3373399c5d565de033c40a39e6f6f9399bb782e)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark 2016-10-10 12:39:59 -07:00 committed by Richard Purdie
parent eedb264387
commit 1d4031a4df
1 changed files with 91 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

124
bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
View File

@ -1531,37 +1531,29 @@
<title>Tasks</title> <title>Tasks</title>
<para> <para>
Tasks are BitBake execution units that originate as Tasks are BitBake execution units that make up the
functions and make up the steps that BitBake needs to run steps that BitBake can run for a given recipe.
for given recipe. Tasks are only supported in recipes and classes
Tasks are only supported in recipe (<filename>.bb</filename> (i.e. in <filename>.bb</filename> files and files
or <filename>.inc</filename>) and class included or inherited from <filename>.bb</filename>
(<filename>.bbclass</filename>) files. files).
By convention, task names begin with the string "do_". By convention, tasks have names that start with "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>
</para> </para>
<section id='promoting-a-function-to-a-task'> <section id='promoting-a-function-to-a-task'>
<title>Promoting a Function to a Task</title> <title>Promoting a Function to a Task</title>
<para> <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. <filename>addtask</filename> command.
The <filename>addtask</filename> command also describes The <filename>addtask</filename> command can also
inter-task dependencies. optionally describe dependencies between the
Here is the function from the previous section but with the task and other tasks.
<filename>addtask</filename> command promoting it to a task Here is an example that shows how to define a task
and defining some dependencies: and to declare some dependencies:
<literallayout class='monospaced'> <literallayout class='monospaced'>
python do_printdate () { python do_printdate () {
import time import time
@ -1569,15 +1561,81 @@
} }
addtask printdate after do_fetch before do_build addtask printdate after do_fetch before do_build
</literallayout> </literallayout>
In the example, the function is defined and then promoted The first argument to <filename>addtask</filename>
as a task. is the name of the function to promote to
The <filename>do_printdate</filename> task becomes a dependency of a task.
the <filename>do_build</filename> task, which is the default If the name does not start with "do_", "do_" is
task. implicitly added, which enforces the convention that
And, the <filename>do_printdate</filename> task is dependent upon all task names start with "do_".
the <filename>do_fetch</filename> task. </para>
Execution of the <filename>do_build</filename> task results
in the <filename>do_printdate</filename> task running first. <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>&nbsp;<replaceable>recipe</replaceable>&nbsp;<filename>-c</filename>&nbsp;<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>&nbsp;<replaceable>recipe</replaceable>&nbsp;<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> </para>
</section> </section>