summaryrefslogtreecommitdiffstats
path: root/bitbake/doc/bitbake-user-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-10-10 12:39:59 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-10-13 23:29:25 +0100
commit1d4031a4dfc3fe633479bb66f97b713be433b49a (patch)
tree29415bdc9a52dd63c6515304479d4875c8c78b3e /bitbake/doc/bitbake-user-manual
parenteedb264387e87e43a51117fbc539993f3aea5bf3 (diff)
downloadpoky-1d4031a4dfc3fe633479bb66f97b713be433b49a.tar.gz
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>
Diffstat (limited to 'bitbake/doc/bitbake-user-manual')
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml124
1 files changed, 91 insertions, 33 deletions
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
index 40f4829e6a..e1b2f2d0b2 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
@@ -1531,37 +1531,29 @@
1531 <title>Tasks</title> 1531 <title>Tasks</title>
1532 1532
1533 <para> 1533 <para>
1534 Tasks are BitBake execution units that originate as 1534 Tasks are BitBake execution units that make up the
1535 functions and make up the steps that BitBake needs to run 1535 steps that BitBake can run for a given recipe.
1536 for given recipe. 1536 Tasks are only supported in recipes and classes
1537 Tasks are only supported in recipe (<filename>.bb</filename> 1537 (i.e. in <filename>.bb</filename> files and files
1538 or <filename>.inc</filename>) and class 1538 included or inherited from <filename>.bb</filename>
1539 (<filename>.bbclass</filename>) files. 1539 files).
1540 By convention, task names begin with the string "do_". 1540 By convention, tasks have names that start with "do_".
1541 </para>
1542
1543 <para>
1544 Here is an example of a task that prints out the date:
1545 <literallayout class='monospaced'>
1546 python do_printdate () {
1547 import time
1548 print time.strftime('%Y%m%d', time.gmtime())
1549 }
1550 addtask printdate after do_fetch before do_build
1551 </literallayout>
1552 </para> 1541 </para>
1553 1542
1554 <section id='promoting-a-function-to-a-task'> 1543 <section id='promoting-a-function-to-a-task'>
1555 <title>Promoting a Function to a Task</title> 1544 <title>Promoting a Function to a Task</title>
1556 1545
1557 <para> 1546 <para>
1558 Any function can be promoted to a task by applying the 1547 Tasks are either
1548 <link linkend='shell-functions'>shell functions</link> or
1549 <link linkend='bitbake-style-python-functions'>BitBake-style Python functions</link>
1550 that have been promoted to tasks by using the
1559 <filename>addtask</filename> command. 1551 <filename>addtask</filename> command.
1560 The <filename>addtask</filename> command also describes 1552 The <filename>addtask</filename> command can also
1561 inter-task dependencies. 1553 optionally describe dependencies between the
1562 Here is the function from the previous section but with the 1554 task and other tasks.
1563 <filename>addtask</filename> command promoting it to a task 1555 Here is an example that shows how to define a task
1564 and defining some dependencies: 1556 and to declare some dependencies:
1565 <literallayout class='monospaced'> 1557 <literallayout class='monospaced'>
1566 python do_printdate () { 1558 python do_printdate () {
1567 import time 1559 import time
@@ -1569,15 +1561,81 @@
1569 } 1561 }
1570 addtask printdate after do_fetch before do_build 1562 addtask printdate after do_fetch before do_build
1571 </literallayout> 1563 </literallayout>
1572 In the example, the function is defined and then promoted 1564 The first argument to <filename>addtask</filename>
1573 as a task. 1565 is the name of the function to promote to
1574 The <filename>do_printdate</filename> task becomes a dependency of 1566 a task.
1575 the <filename>do_build</filename> task, which is the default 1567 If the name does not start with "do_", "do_" is
1576 task. 1568 implicitly added, which enforces the convention that
1577 And, the <filename>do_printdate</filename> task is dependent upon 1569 all task names start with "do_".
1578 the <filename>do_fetch</filename> task. 1570 </para>
1579 Execution of the <filename>do_build</filename> task results 1571
1580 in the <filename>do_printdate</filename> task running first. 1572 <para>
1573 In the previous example, the
1574 <filename>do_printdate</filename> task becomes a
1575 dependency of the <filename>do_build</filename>
1576 task, which is the default task (i.e. the task run by
1577 the <filename>bitbake</filename> command unless
1578 another task is specified explicitly).
1579 Additionally, the <filename>do_printdate</filename>
1580 task becomes dependent upon the
1581 <filename>do_fetch</filename> task.
1582 Running the <filename>do_build</filename> task
1583 results in the <filename>do_printdate</filename>
1584 task running first.
1585 <note>
1586 If you try out the previous example, you might see
1587 the <filename>do_printdate</filename> task is only run
1588 the first time you build the recipe with
1589 the <filename>bitbake</filename> command.
1590 This is because BitBake considers the task "up-to-date"
1591 after that initial run.
1592 If you want to force the task to always be rerun for
1593 experimentation purposes, you can make BitBake always
1594 consider the task "out-of-date" by using the
1595 <filename>[</filename><link linkend='variable-flags'><filename>nostamp</filename></link><filename>]</filename>
1596 variable flag, as follows:
1597 <literallayout class='monospaced'>
1598 do_printdate[nostamp] = "1"
1599 </literallayout>
1600 You can also explicitly run the task and provide the
1601 <filename>-f</filename> option as follows:
1602 <literallayout class='monospaced'>
1603 $ bitbake <replaceable>recipe</replaceable> -c printdate -f
1604 </literallayout>
1605 When manually selecting a task to run with the
1606 <filename>bitbake</filename>&nbsp;<replaceable>recipe</replaceable>&nbsp;<filename>-c</filename>&nbsp;<replaceable>task</replaceable>
1607 command, you can omit the "do_" prefix as part of the
1608 task name.
1609 </note>
1610 </para>
1611
1612 <para>
1613 You might wonder about the practical effects of using
1614 <filename>addtask</filename> without specifying any
1615 dependencies as is done in the following example:
1616 <literallayout class='monospaced'>
1617 addtask printdate
1618 </literallayout>
1619 In this example, assuming dependencies have not been
1620 added through some other means, the only way to run
1621 the task is by explicitly selecting it with the
1622 <filename>bitbake</filename>&nbsp;<replaceable>recipe</replaceable>&nbsp;<filename>-c printdate</filename>.
1623 You can use the
1624 <filename>do_listtasks</filename> task to list all tasks
1625 defined in a recipe as shown in the following example:
1626 <literallayout class='monospaced'>
1627 $ bitbake <replaceable>recipe</replaceable> -c listtasks
1628 </literallayout>
1629 For more information on task dependencies, see the
1630 "<link linkend='dependencies'>Dependencies</link>"
1631 section.
1632 </para>
1633
1634 <para>
1635 See the
1636 "<link linkend='variable-flags'>Variable Flags</link>"
1637 section for information on variable flags you can use with
1638 tasks.
1581 </para> 1639 </para>
1582 </section> 1640 </section>
1583 1641